Assignment: Assigns a value to a variable.
_var = expression
First type the name of the variable, then an equal sign (assignment operator), and an expression. An expression can be a variable, a string, a number, a file name, an arithmetic expression, or a function. For example:
_count = 0_count = _count + 1
_author = "dittmar, p"
_filename = <rn.txt>
BEGIN/END: Forms a block of statements that are treated as a group.
BEGIN may appear on the same line as an IF statement.
A BEGIN/END block usually follows an IF or ONEXIT statement.
To use this statement, type BEGIN before the statements you want grouped together. Type END after the statement group. For example:
IF
(_status = "NOT CONNECTED") BEGIN
ECHO "DIALING..."
SEND "ATDT 555-5555"
END
This example executes every line between BEGIN and END only if the value of _status is "NOT CONNECTED". Otherwise, the script continues after the END statement.
BREAK: Sends a break to the host system.
BREAK [n [MILSEC[S]]]
Enter the number, n, as either a variable or an integer. If n is not entered, 750 is the assumed value. For example:
BREAK 500
sends a break 500 milliseconds in duration.
CAPTURE: Turns on or off transcript capture for your online session.
CLOSE: Closes the currently open file.
For example:
CLOSE
closes the data file that was opened by the OPEN statement.
If an error occurs at the end of the file, the _$filerror system variable is non-zero.
CONTINUE: Continues processing a script beyond the current SEND, WAIT FOR, and TRYAGAIN statements.
For example:
SEND
"X"
WAIT
FOR "LOGINID" CONTINUE
FOR 20 SECONDS GOTO @ERR
SEND _loginid
If "LOGINID" is received from the host within 20 seconds, the script continues at the SEND statement.
DELETE: Deletes a specific file.
For example:
_filename
= <oldfile.txt>
DELETE _filename
deletes the file named oldfile.txt from the Uscripts folder. To delete a file from a different folder, give the full path.
If an error occurs, the _$filerror system variable is non-zero.
Deleting the Session History
Command format: DELETE HISTORY Y
Enter DELETE HISTORY at an arrow prompt (=>) to remove all the L-numbers. The history record of your entire search session is also removed and cannot be displayed. You can no longer see the deleted L-numbers, the SELECT or EXPAND requests, or the order or print request numbers when you display the session history. You are asked to confirm the delete request before any action is taken. You may confirm the request by entering Y at the prompt or by entering Y on the same line as DELETE. If you have used the novice version of the command, you receive confirmation that the deletion has occurred. If you have used the expert version, no confirmation is given.
When you delete the history, the E-number list is not deleted. Print and order requests are not cancelled. To see the E-number list, enter DISPLAY SELECT at an arrow prompt (=>). To see the print request numbers and status, enter DISPLAY PRINT at an arrow prompt (=>). You cannot see the order request numbers if the history has been deleted. Therefore, it is recommended that you display the session history and record the order request numbers before entering DELETE HISTORY.
To reset to L1 by deleting the history of the session:
=> del his y
To display session history after deleting the history:
=> dis his
ECHO: Displays a character string or variable on the page.
ECHO "string" [NOCR]
The string can be zero or more characters, variables, or both. A carriage return is included after the string. To suppress it, use the NOCR keyword. For example:
_var
= "example"
_item = "ECHO statement."
ECHO "This is an _var of the " NOCR
ECHO _item
displays
This is an example of the ECHO statement.
on your screen.
The ECHO statement is not used to send commands to an online host (use the SEND statement). The results of ECHO statements and host commands are mixed in the session window and transcript. As a result, it can appear that commands are being sent to the host when they are not. For example,
ECHO "Enter your search term:"
appears as
=> Enter your search term:
on STN.
You may wish to use an extra ECHO to avoid this. For example,
ECHO
"" \* outputs a blank line to
the screen
ECHO "Enter your search term:"
appears as
=>
Enter your search term:
in the STN session and transcript.
EDIT: Interacts with the script processor by pausing the script before sending a command to the online host.
EDIT {ON | OFF}
An "Enter user data" box with the next command in it appears, allowing the command to be edited before it is sent. The changes made in the text editing box are not saved in the script file.
You may use \! as a shortcut for the EDIT statement. Use \! on the => and : statement lines for STN scripts. The \! operator must occur at the end of the statement.
EXEC: Executes another script from within a script.
EXEC <file name>
The EXEC command is used to execute a second script from within a script (master script). The master script requires the file name of the second script:
EXEC <secondscript>
Scripts may be nested eight levels deep. Variables defined in the calling script are available in the called script. When the called script completes, processing continues on the line immediately after the EXEC statement in the calling script. For example:
_filevar
= <SECONDSCRIPT.sc>
EXEC _filevar
ECHO "_filevar has completed processing."
executes the script SECONDSCRIPT.sc. Then it returns to the calling script and prints:
SECONDSCRIPT.sc has completed processing.
All scripts that are executed must reside in My Files > Scripts. When scripts are stored in a folder, the path name is required, e.g. when the script is stored in the folder /herbicide/ the EXEC statement is:
EXEC <herbicide/secondscript>
EXIT: Defines a point to leave the script.
EXIT has no parameters.
An exit is assumed after the last statement in a script. Thus, an EXIT statement is not required in any script. More than one EXIT statement may be used in a script.
If an ONEXIT statement exists in a script, the ONEXIT block is executed before exiting. If the ONEXIT statement includes an EXIT statement, an exit occurs immediately when that EXIT is executed.
GET: Accepts input from the keyboard.
GET _varname [HIDDEN] [LABEL="string"]
When a GET statement is reached in the script, a text entry box is displayed in which the user may type. Typed characters, up to but not including the first carriage return, are placed in _varname.
For example, a user is requested to type the date of the latest alert run, which is assigned to the variable_update:
GET _UPDATE LABEL="Enter today's date in YYYYMMDD format"
The text defined by the label appears at the top of the text entry box:
All typed input is scanned for a colon character (:). If found, GET returns only the characters that follow the colon.
If the HIDDEN keyword is present, the typed characters are not displayed in the input box.
If both the HIDDEN and LABEL keywords are present, HIDDEN must be first.
Note: For the GET command, the word LABEL is an attribute, which define what the GET command is to do. See also Script Labels.
GOSUB: Branches to a different location (a subroutine) in the script with the option of returning to the statement that follows GOSUB.
GOSUB @label
Subroutines are useful when an identical set of statements is executed from various points in the script.
GOSUB has only one parameter, a label. When GOSUB is reached, script processing moves to the indicated label and continues processing until a RETURN statement is reached. The RETURN statement causes the script to continue with the statement following the GOSUB statement.
GOSUBs may be nested up to eight levels.
For example:
ECHO
"Right before the GOSUB."
GOSUB @SUBROUTINE
ECHO "Right after the GOSUB."
EXIT
@SUBROUTINE
ECHO "Within the GOSUB."
RETURN
displays:
Right before the GOSUB.
Within the GOSUB.
Right after the GOSUB.
GOTO: Directs script processing to a line that is not directly after the current line of a script.
GOTO @label
GOTO is similar to GOSUB except that there is no option to RETURN.
For example:
IF
(_var1 = "FIRST") GOTO @LABEL1
ECHO "Value of var1 is not FIRST."
EXIT
@LABEL1
ECHO "Value of var1 is FIRST"
EXIT
outputs only one of the above ECHOed lines, depending on the value of _var1.
IF: Executes one or more statements based on a condition or criteria.
IF (condition) block [ELSE block]
The IF/ELSE statement forms a construct that decides which statement to execute next. If the condition is true, the statement or block directly following the IF is executed. If the condition is false, the statement or block directly following the ELSE keyword is executed. If the condition is false and there is no ELSE keyword, the statement following the end of the IF block is executed.
Use a BEGIN/END block when you want to execute more than one statement after IF or ELSE.
For example:
\*
If no phone number was given, ask for it. Otherwise,
\* display the number. In either case, dial the number.
IF (_phoneno = "") BEGIN \* multi-statement
block
ECHO "Enter phone number:"
GET _phoneno
END
ELSE
ECHO "Dialing _phoneno" \* single-statement
block
SEND "ATDT _phoneno"
Note that the SEND statement is outside the IF/ELSE construct. It is executed regardless of the condition.
ONEXIT: Specifies a set of statements to always execute before leaving a script.
ONEXIT block
The ONEXIT statement may be placed anywhere within a script. An ONEXIT block cannot contain a GOTO or RETURN statement.
When the script processor reaches an EXIT statement and an ONEXIT block has been defined, processing jumps to the ONEXIT block. After the ONEXIT block has been completed, the script ends. An EXIT statement within an ONEXIT block causes an immediate exit (the ONEXIT block is not executed again).
The block portion of the statement may be entered as one line, or as a set of statements between BEGIN and END.
For example, the statements:
ONEXIT
BEGIN
ECHO "These two lines will always be"
ECHO "executed upon exiting the script."
END
cause the two lines to be displayed to the screen when you leave the script.
OPEN: Opens a new or existing file from within a script.
OPEN [<file name>] [ {/R | /W} ]
The file to be opened is a .data file stored in My Files > Scripts. The .data file is created:
Outside of STNext (e.g., in Notepad or Notepad++, with a .data extension, and imported into STNext using the Import Script feature.
Create a file in a folder by right-clicking and selecting New | Text Document … when the file is placed in the folder, you can edit the complete name. Then open and edit the file.
With Notepad open, select File | Save As, change the type to All Files, and then enter the file name with the .data extension.
Within STNext, via a running script, so long as the file did not exist prior to it being opened.
When files are stored in a folder, the path name is required, e.g., the file names.data in the folder /herbicides/ is opened with:
OPEN <herbicide/names>
Scripts that are .data files include the Data icon.
The file name is optional. If no file name is supplied, you are prompted to enter one.
The /R option opens the file to read only. The /W option allows both reading and writing in the file. The default option is /W.
The OPEN command is used in combination with the READ or WRITE command. OPEN appears before READ or WRITE:
OPEN/READ: opens a .data file, reads the first single line and assigns the value to a variable:
OPEN <herbicide/control>
READ _script
Further READ statements in the script read subsequent lines of the .data file.
The script above reads the first line of data script <new 1> and extracts its first line (=> s ALABAMA OR ARKANSAS). To read subsequent lines of the data script, looping is required. Not shown here.OPEN/WRITE: opens a .data file and writes a line in the open file. All data written to the file is appended to the end of the file:
_error = "Command timed out. Error ##36."
OPEN <errors>
WRITE _error
CLOSE
places the message Command timed out. Error #36 in a file named errors.data.
If an error occurs, the _$filerror system variable is non-zero.
PAGE: Forces the captured transcript to begin a new page.
PAGE
Page breaks appear when Browsing a standard transcript as
<------Page Break------>
and are preserved when saved as RTF.
PAUSE: Halts script processing for a period of time or until a specific time of day.
PAUSE {n [SECOND[S]] | [UNTIL time]}
Enter the number of seconds, n, as an integer or a variable. If n equals zero, the pause is forever.
The UNTIL time option allows you to specify a certain time of the day, using a 24-hour clock.
For example:
PAUSE
1 SECOND \*
pause for 1 second
PAUSE UNTIL 14:45 \*
pause until 2:45 pm
Prompt (=> and /): The => and : statements, also known as prompt statements, are shortcuts for a WAIT/SEND combination.
=> [host-command] [\!] [\> _var] (primary prompt statement)
: [STN-reply] [\!] [\> _var] (STN secondary prompt statement)
The => command waits for a primary or level 1 prompt, "=>" on STN. The : command waits for a secondary or level 2 prompt, ":" on STN. After the prompt is received, host-command or STN-reply is sent to the online host. For example:
=> del history
: y
is equivalent to:
SEND "" \* Cause an arrow prompt.
WAIT
FOR "=>" \*
Wait for the arrow prompt
SEND "del history" \* and
send a delete command.
WAIT
FOR ":" \*
Wait for the confirmation question
SEND "y" \*
and reply.
In each case in the example, STNext waits to receive a command line from STN. After receiving the arrow prompt, STNext sends a delete history command and then waits for a secondary prompt from STN. STN responds with "DELETE ALL L# ITEMS? (Y)/N:", which STNext recognizes as a level 2 prompt
The => statement works for STN and online hosts. The : statement is for STN only.
Use the \! operator if you want to edit the host command before it is sent (see also the EDIT statement).
Use the \> operator to assign the L-number result of the command to a variable. For example, suppose the search command in the following statement produces L2 and 1492 answers:
=> s acid cow \> _lnum
The value of _lnum will be "L2". Furthermore, the # operator can be used with _lnum to retrieve the number of answers in an L-number. The statement:
ECHO "_lnum contains #_lnum answers."
displays:
L2 contains 1492 answers.
READ: Reads a single line from the OPEN file and stores the value, without a carriage return character, in _varname.
READ _varname
For example:
@LOOP
READ _LINE
If _LINE = “*****” GOTO @END
ECHO “ -- Read _LINE”
GOTO @LOOP
@END
You need to get the data from the data file into the script and searched. The following script accomplishes that:
=> file caplus
=> search (epidemi? and (influenza? or flu?))\> _LNUM1
ECHO "Reading data file"
OPEN <input>
Note: "input" is the name of a multi-line data file saved in your scripts, and the last line in the data file is "*****"
@LOOP
READ _LINE
If _LINE = “*****” GOTO @END
ECHO “ -- Read _LINE”
= > search _line and _LNUM1\> _LNUM1 (The trick her is to repeatedly reassign the LNUM1 variable.)
GOTO @LOOP
@END
CLOSE
The file input.data is opened and the first line is read into the variable _line.
The input.data file could be:
S Alabama or Arkansas
S Delaware or New York or Pennsylvania or Ohio
*****
If an end-of-file condition is reached or an error occurs, the _$filerror system variable will be non-zero.
RETURN: Returns to the point from which a subroutine was invoked by a GOSUB statement.
RETURN
For example:
GOSUB
@SUBROUTINE
ECHO "processing will return to this point."
EXIT
@SUBROUTINE
ECHO "After printing this line..."
RETURN
displays the following:
After printing this line...
processing will return to this point.
SEARCH: Performs a search.
If you do not append a search code, the search is performed in the Basic Index.
SEND: Sends a character string to the online host.
SEND "string" [EDIT] [HIDDEN] [NOCR]
(Technically, the string is sent to the communication port specified in the logon setup. Therefore, for example, a string can be sent to a modem before STN Express is connected to the host.)
The string and other parameters may occur in any order after the SEND statement. The "=>" and ":" statements are specific forms of SEND.
EDIT is an option that allows the string to be edited before it is sent. EDIT works as \! does in the => and : statements.
HIDDEN does not display the string as it is sent. This is useful when sending passwords.
A carriage return is automatically included after the string. To suppress it, use the NOCR keyword.
For example:
SEND
"+++" NOCR
SEND "ATDT 555-1212"
sends:
+++ATDT 555-1212
to the modem.
STNLOGON: Executes the STNLOGON script that logs you on to STN International.
STNLOGON
STNLOGON assumes that there is already a connection to STN. Specifically, STNLOGON sends a carriage return and expects the reply to be "Welcome to STN International! Enter x:".
STRUCT DETAILS: Inserts the structure attributes details for a L-number.
If there are no structure details available for the L-number, the system displays the message "There are no structure details available for this L-number."
The syntax for this command is STRUCT DETAILS L### | VARIABLE |.
The maximum value of an L-number is L999.
The following can be used in a script to automate the insertion of structure details:
GET _lnumber LABEL="Enter the L-number of the Structure"
STRUCT DETAILS _lnumber
SUBSTR: Takes a string of characters in a variable and returns a "substring" or portion of the string.
SUBSTR (_var, begin, length)
The returned substring begins with character number begin and continues for length characters. Begin and length may be literal numbers or variables. For example, the statements:
_var1
= "xxx remove this portion xxx"
_var2 = SUBSTR(_var1, 5, 19)
ECHO _var2
display the following contents of _var2:
remove this portion
SUBSTR may be used in conditions. For example:
_len
= 3
IF (SUBSTR(_var1,1,_len) = "xxx") GOTO @label
When the script runs, if begin is beyond the end of the string, a variable substitution error is given.
TRYAGAIN: Repeats the previous SEND statement a specified number of times, part of a WAIT block.
TRYAGAIN n [TIMES] [ [THEN] block]
This statement works only in the context of the SEND-WAIT statement pair. It repeats the previous SEND up to n times. After the nth attempt, processing either performs the THEN block or EXITs.
For example:
SEND
"ATDT 555-1212"
WAIT
FOR "CONNECT" CONTINUE
FOR "NO CARRIER" EXIT
FOR 5 SECONDS
TRYAGAIN 5 TIMES THEN GOTO @failed
This script sends the phone number and waits five seconds for either CONNECT or NO CARRIER. If the response is not received, the phone number is sent up to five more times. If the expected response is still not received, the process jumps to the @failed label.
UPLOAD: Uploads a structure query.
UPLOAD [LNUM _var1,_var2,_var3...] <file name>
The result of the UPLOAD in a structure searchable file is an L-numbered structure query that is automatically displayed with all structure attributes.
The LNUM keyword indicates the beginning of a list of variables. The variables are assigned the L-number or L-numbers of the uploaded structure. Usually, only one variable is needed.
Multiple variables are needed when a reaction query with multiple participants is uploaded in an STN file that does not support reaction searching. In that situation, each of the participants is uploaded into its own L-numbered query. Commas must separate variables in the list.
<file name> is a full path to a .str query file created in the STNext Structure Editor stored in My Files > Structures.
For example:
UPLOAD LNUM _line1 <drugs/pantoprazole>
This statement uploads the structure query pantoprazole from the folder /drugs/ to STNext and stores the resulting L-number value in the _line1 variable.
Note: The path for files referenced for upload cannot have two folders in front of the file name (e.g., UPLOAD LNUM _line1 <drugs/m_to_p/pantoprazole>).
Use STRUCT DETAILS to display details for an L-number's structure.
USER: Temporarily halts script processing and gives control of the online session to the user.
USER
Control is returned to the script when you click the Resume button.
WAIT: Pauses script processing until a specific response is received from the online host.
WAIT [ _var1] [LNUM _var2] for-list
This statement results in data being read from the incoming communication port one line at a time. A line includes everything up to a carriage return.
After WAIT is executed, _var1 contains the last line received from the host.
LNUM _var2 puts an L-number into the variable _var2.
for-list is one or more:
FOR for-condition [THEN] block
This is defined as: "If for-condition is met, then execute these statements."
The block is optional, except for the last for-condition. Often the block contains a CONTINUE statement.
For-condition is either:
"string" (substring received from host)
or:
n [SECOND[S]] (passing of time, n, can be an integer or a variable)
If n is zero, the WAIT is forever.
See the example at the TRYAGAIN statement.
WRITE: Writes a line of text into the currently-open file.
WRITE "string" [NOCR]
WRITE places string in the open file, followed by a carriage return. If the NOCR keyword is present, the carriage return is suppressed. Lines are always appended to the end of the file. To erase the contents of the file before writing to it, use the DELETE statement.
The command WRITE is used in combination with OPEN:
_error = "Command timed out. Error ##36."
OPEN <errors>
WRITE _error
CLOSE
The errors.data file is opened and the message Command timed out. Error #36 is appended to the end of the file.
If an error occurs, the _$filerror system variable is non-zero.