Procedure Variables

Variables can be used in the enhanced procedure mode, in the user text, as well as in the internal language elements (*-statements). These procedure variables are not to be confused with BS2000 procedure variables, and can only be used in CFS procedures and Startup files.

CFS Procedure variable names are identified by being prefixed, normally with '&'. The procedure statement *SET PAR=x (see the next section, "Procedure Language Elements") can be used to redefine the parameter prefix to any special character.

The name of a CFS Procedure variable can contain 1 to 20 alphanumeric characters. The only special character allowed within the name of a procedure variable is '-'. The CFS procedure variable can also begin with a numeral.

The contents of CFS procedure variables can be 1 to 80 characters. When starting the procedure, or when assigning the null string (&var=''), the contents of the variable will be set to binary zero. Exception: CFS-internal procedure variables. These procedure variables have fixed, predefined names, and will be loaded by CFS automatically with the required values. CFS-internal procedure variables may not appear in the *PROC statement of the CFS procedure (see page 19-).

Double substitution: The contents of a procedure variable will be interpreted as the name of another procedure variable, if the variable is specified in the form &&var.

Example: The variable &CX is assigned the value 'VAR1'. By specifying &&CX, the contents of the variable &VAR1 will be used. An example of double substitution can be found on page 20-.

The following CFS-internal procedure variables are available:

&ACCT One to eight digit account number from which CFS was loaded.

&ACCT(tsn) Account nuumber of the LOGON command of the specified TSN. The TSN must always be specified as a four digit number. The account number of a foreign userid can only be ascertained if CFS was loaded from TSOS. An example of the usage of this variable can be found on page 19-.

&ARGC Number of positional parameters passed when calling the CFS procedure. Empty parameter positions (par1,,par3) are included in the count.

&BS2PL BS2000 Procedure level (Procedure Level Number).

'0': CFS was not called from a DO procedure. >'0': CFS was called from a BS2000 DO procedure.

&CFSINCON Was the current CFS program called from a Connection ? Y | N.

&CFSMSG This 80 character variable provides access to the information that, in dialog mode of CFS, is displayed in the status line of the last screen to have been displayed. Error messages from the file list, as well as Selection mask error messages will be passed to the variable.

The CFSMSG variable will contain an empty string ('') if the message from the last screen was the standard "Help: ?/?all/??".

When assigning the CFSMSG variable, CFS will convert the text to upper case.

&CMDMSG This 80-byte variable can be used to access the message displayed by the last command to have been executed from within the procedure by a statement */cmd (any BS2000 command). Error messages, as well as information from the BS2000 command, will be passed to the variable.

If the BS2000 command displays multiple messages, the CMDMSG variable will only contain the first record.

The variable CMDMSG will contain an empty string ('') if the last */cmd statement did not display any messages.

&CONx If at the time the &CONx (0 <= x <= 9) variable is interrogated, a Connection with the respective number exists, then the variable will contain the application name to which the Connection was opened (e.g. $DIALOG, $CONSOLE, ... ). If no Connection exists at the time, the variable will contain the empty string ('').

&CONxH If, at the time the &CONx (0 <= x <= 9) variable is interrogated, a Connection with the respective number exists, then the variable will contain the name of the host system to which the Connection was opened.

&CONxJ If, at the time the &CONx (0 <= x <= 9) variable is interrogated, a Connection with the respective number exists to $DIALOG, then the variable will contain the Job name of the dialog task (.name   LOGON ...).

The variable will contain the empty string, if

a) the Connection was not made to a dialog task,

b) no job name was specified in the LOGON command,

c) the installed version of BS2000 if lower than 9.0.

&CONxT If, at the time the &CONx (0 <= x <= 9) variable is interrogated, a Connection with the respective number exists to $DIALOG, then the variable will contain the TSN of the dialog task. The variable will contain the empty string ('') if the Connection was not made to a $DIALOG task.

&CONxU If, at the time the &CONx (0 <= x <= 9) variable is interrogated, a Connection with the respective number exists to $DIALOG, then the variable will contain the userid of the LOGON command under which the Connection was opened. The variable will contain the empty string ('') if the Connection was not made to a $DIALOG task.

&DATE Current date in the form: yy-mm-dd

&DATE4 Current date in the form: yyyy-mm-dd (4-digit representation of the year)

&DATE2 Current date in the form: dd.mm.yy

&DATE42 Current date in the form: dd.mm.yyyy (4-digit representation of the year)

&DAY Current day of the week, coded as follows:

1 = Monday, 2 = Tuesday, 3 = Wednesday, ...., 6 = Saturday, 7 = Sunday.

&DAY2 Current day of the week in English text.

&DAY2G Current day of the week in German text.

&DISP-POS For SAM and PAM files in Display Mode, the record/block number will be included with the first record which is to be displayed. For ISAM files, the key of the first displayed record will be included.

&DISPEOF Displays if the end of the file was reached in Display mode when executing the last command (e.g. +n or S) or if a DMS error was encountered.

'N' The last command did not result in an EOF condition.

'Y' The last command resulted in an EOF condition.

'DMSnnnn' A DMS error with the specified code was encountered.

&FROM If the CFS procedure was called from a Connection by using the escape symbol (^DO xxxx), then this variable will contain the Connection number from which the procedure was called. If the procedure was called from the main CFS task (DO xxxxx), then the variable will contain the value 'M' (Main task).

&HOST Name of the host system (one to eight characters) on which CFS is loaded.

&LISTEND The variable contains the number of entries in the file list. Hidden entries are not included.

&LISTENTRY The variable contains the details of the first file list entry currently displayed on the screen. The size of the variable is either 64 or 69 characters, depending on whether a User Option was specified at file selection time or not.

&NEXTENTRY The variable contains the details of the entry in the file list following &LISTENTRY. If no following entry exists, the variable will contain the value '' (null string).

&LOGNAM Job name from the LOGON command (/.name LOGON ... ).

If no job name was specified in the LOGON command, then the variable will contain the empty string ('').

&LOGNAM(tsn) Job name from the LOGON command of the specified TSN. The TSN must always be specified as a four digit number. The job name of a foreign TSN can only be ascertained if CFS was loaded from TSOS. An example of the use of this variable can be found on page 19-.

&MODE Task mode under which CFS is running: 'DIALOG' | 'BATCH'

&NEXTCON contains the number of the next free Connection to be opened. If no Connections have been opened, NEXTCON will have the value 0. If Connection 0 is already open, NEXTCON will have the value 1, and so on. If all Connections have been opened, NEXTCON will contain an empty string ('').

&POSLIST contains a five digit number which identifies the position in the file list occupied by the entry on the first line of the current screen. See also the command Pn on page 7-.

&POSUACT contains a five digit number which identifies the position in the file list occupied by the entry marked with a %-Action Code. See also the command Pn on page 7-.

&RDMASKIN contains a description of the transmission key that was used to acknowledge the last mask issued by *RDMASK. Example: DUE, which here means the ENTER key. For further information on the RDMASK procedure statement, see page 19-.

&SEARCHRET This variable contains the return code of the last search command performed by CFS.

Return code 'ERR' Syntax error in defining the search condition.

Returncode '' Search argument was not found.

Returncode 'nnn' one to six digit decimal number.

Pure search: Column of first hit

Search and Replace: Number of hits

&SEL-USID PVS and userid of the selected data objects.

&SLABEL Name of a variable branch label (*SKIP &SLABEL). The variable must have been referenced previously in an *ON %OUT=(file) statement. The file in which the search strings of the %OUT statement are defined must conform to the following format:

seachstring-1 .label-1

...

searchstring-n .label-n

&SLABEL contains the name of the label corresponding to the first search string to find a match. An example of this construction can be found on page 19-.

&SEL-LIB Name of the library containing the selected elements.

&STATNAM Station Name, from which CFS was called.

&STATNAM(tsn) Station Name from which a dialog task with the specified TSN was started. The TSN must always be entered as a four digit number. The station name of a foreign TSN can only be ascertained if CFS was loaded from TSOS. An example of the use of this variable can be found on page 19-.

&TIME Current time in the format: hhmmss

&TIME2 Current time in the format: hh:mm:ss

Each time this variable is interrogated, the current time will be substituted.

&TSN Four digit TSN of the task from which CFS was called.

&USER-ID Userid (one to eight characters) under which CFS was loaded.

&USER-ID(tsn) Userid of the LOGON command of the specified TSN. The TSN must always be entered as a four digit number. The station name of a foreign TSN can only be ascertained if CFS was loaded from TSOS. An example of the use of this variable can be found on page 19-.

Notes:

The end of a procedure variable name is marked with any special character, with the exception of '-'. For example, a blank could be used to indicate the end of a variable name. If a variable is to replace a portion of the text in a CFS procedure data record (no asterisk in 1st column), it should be noted that one fullstop will be removed when the variable substitution takes place.

For example, assume that the procedure variables &N and &LOGNAM have the values '1' and 'MEYER' respectively. After substitution, a record "OC&N/.&LOGNAM.&N LOGON..." will contain the value:

"OC1/.MEYER1  LOGON ...".

Using double substitution, CFS-internal variables can be evaluated, even though their value cannot be determined beforehand.

For example, assume a CFS procedure TEST is called from Connection 2 with ^DO TEST. In the procedure, the variable &CX will be loaded with 'CON2H' by the statement &CX = 'CON'&FROM.'H' (i.e. with the description of the CFS procedure variable &CON2H). The procedure statement *WRITE '&CX = &&CX' will result in the program output 'CON2H = HOST1', where HOST1 is the host name to which Connection 2 was opened.

When calling a procedure, the variables used in it can have predefined values. This is done in the same way as for a BS2000 DO procedure, by specifying the parameters after the name of the procedure being called:  DO procedure, par1, par2, ......

The assignment of CFS procedure variables must be done as either positional parameters, (value), or as keyword parameters, (par=value), depending on the particular PROC statement. For further information, see pages 19- and 19-.

CFS Procedure Variables can also be used in Menu files. For further information, see Chapter 10 "Menu System for Connections", page 10-.

Procedure variables and *PROC statements: CFS procedure variables will be created automatically the first time they occur in the procedure. The CFS procedure language also permits a *PROC statement at the beginning of the procedure, in which some or all of the variables can be declared. For further information, see page 19-.