|
CFS offers the user the possibility of executing a sequence of commands and/or selection actions in a procedure mode. The commands to be executed could be contained in a
- BS2000 DO or Enter Procedure
- CFS Command Procedure
- CFS Startup File
The CFS Procedure language described in this chapter is equally valid for BS2000 DO or Enter procedures, CFS command procedures (DO command), or for CFS Startup files.
In the CFS procedure mode, the necessary input (selection conditions, Variable Actions, commands, Connection input) will be expected from SYSDTA. If CFS input is to be accepted from SYSDTA, task switch 1 should be set to ON.
CFS can be used in procedures in two different ways:
a) Basic mode: In this mode, only input for the first CFS screen will be accepted. This input includes: selection conditions, Variable Actions and documentation file specifications.
The procedure will proceed as follows: After the relevant files or library elements have been selected on the basis of a selection record, a Variable Action (if defined in the procedure by a ON&... record) will immediately be executed. A documentation file will be created, if specified.
The entire CFS program section controlling the execution of commands (second CFS screen) is skipped in the basic procedure mode. This mode allows relatively simple procedures to be created in order to select certain data objects and to execute a Variable Action on all these files.
The basic CFS procedure mode is invoked if task switch 11 is set. In addition, all selection records must be headed *001. For further information, see page 19-.
Basic mode is only possible if called from a BS2000 DO or Enter procedure. It is not applicable in CFS command procedures.
b) Enhanced Procedure Mode: This mode simulates the full screen dialog with all input and prompts.
In the enhanced procedure mode, files can be marked with individual Action Codes, and then subsequently processed (e.g. with Modify). Connections can be opened, and various input passed to these Connections. The latter is possible even if CFS is running as an Enter job.
The only drawback to the enhanced procedure mode is that all program input required must be predefined very accurately in the procedure file.
When running in the enhanced procedure mode, task switch 11 must not be set. The file selection statements must begin with *002. Following entries for the CFS command field must not have the *002 header.
If CFS is to be called multiply from a BS2000 DO procedure, the /SYSFILE SYSDTA=(SYSCMD) command must be issued before each CFS call.
Relevant Task Switches for the Procedure Mode
/SETSW ON=1 CFS requests all input with RDATA from SYSDTA. The /SYSFILE SYSDTA=(SYSCMD) command must therefore be entered in a BS2000 procedure. /SETSW ON=1 is necessary for both procedures with *001 records (basic mode), as well as procedures with *002 records (enhanced mode).
/SETSW ON=4 The scope of the output protocol from CFS is reduced to a minimum. In enhanced procedure mode in particular, the masks produced by records read from SYSDTA will not be output (WROUT).
/SETSW ON=11 Prerequisite for basic mode procedures (*001).
Task switch 1 must always be set in conjunction with switch 11.
This switch may not be set for enhanced mode procedures.
/SETSW ON|OFF=31 If an error occurs during the processing of the ON©... / ON&ADD... / ON&SEL... Variable Actions, task switch 31 will be set (SETSW ON=31). It is thus possible to test for a successful conclusion to the Variable Action from within a following section of the procedure. For example, an automatic ERASE operation may only be carried out on files added to a library if the ADD operation was itself successful (task switch 31 must not be set).
Task switch 31 will also be set by CFS if no data objects meeting the specified selection criteria are found, or when no dates are found using the SI/SIL/SIS commands.
In the Basic mode of CFS, only input records with a *001 header (or continuation records) will be read from SYSDTA.
No further input will be expected by CFS after reading in the selection conditions and the Variable Actions. The portion of the program that displays the file list and processes the commands will be skipped. CFS proceeds straight to the execution of a Variable Action (if specified) in the form ON&... .
The termination query is also skipped after executing the Variable Action for all the selected data objects. If another *001 record appears on the SYSDTA input medium, then, as described above, it will used as input for the CFS Selection mask. CFS will be terminated when the End of File condition is reached on SYSDTA. This will be, for example, when the next BS2000 command is encountered in a DO procedure.
The Selection criteria are detected in the basic procedure mode by the record having a *001 header. Together with task switches 1 and 11, this header will result in CFS switching to basic procedure mode.
Format of *001 Records
*001 select=par [; select=par ....... ; select=par ]
select Keyword, or abbreviation, for a selection mask field. CFS will substitute spaces as parameter values for those keywords not specified.
par Value for the respective Selection mask field.
Between a parameter value and another keyword, a semicolon is to be used as a separator character.
Only the first 80 bytes of each input record will be evaluated. If an input record is longer than 80 bytes, or if it is required to spread the record over many lines to help readability, a continuation character, "-", must appear in the last position. There is no limit on the number of continuation characters that may be used.
The following rules are valid for keywords:
Generally, the field descriptions of the CFS Selection mask items are to be used as keywords. Right-most portions of the keywords can be omitted, so long as the portion used is unique.
For example, FI= can be used instead of FILENAME-SELECT=. However, F= cannot be used since it is not unique; two fields in the Selection mask begin with F; FILENAME-SELECT and FCBTYPE.
The shortest abbreviations of the respective keywords are listed below:
FI --> FILENAME-SELECT
USER-I --> USER-ID
LA --> LAST PAGE
AG --> AGE
FCB --> FCBTYPE
VOL --> VOLUME
SH --> SHARE / NONSHARE
ACC --> ACCESS
PAS --> PASS
SO --> SORT OPTION
U --> USER OPTION
DOC --> DOCUMENTATION
VAR --> VARIABLE ACTION
*001 FILENAME-SELECT=CFS;VARIABLE ACTION=ON© ''='$TSOS.'
*001 USER-ID=(SYSDTA);USER OPTION=LACC>90;-
DOC=LST.EXPORT;VAR=ON&TSOSMT GEN SAVTAP,VSNOUT=(TAP001,TAP002)
*001 FILE=OLDLIST LIST.EXPORT;VAR=ON&/ERASE
*001 FILE=.LST;AGE=0;VAR=ON&ADD LIB.LST
Notes:
*001 records may not be used in Startup files and CFS command procedures. In these types of procedures, the parameter selection must only be done using *002 records in the enhanced procedure mode (see below).
If files are to be added from a Basic mode procedure to a library that does not yet exist (see last example), a PLAM library will be created by CFS.
Parameterisation using Job or SDF-P Variables
If the construct &(name) appears anywhere in a data record of a CFS procedure, the CFS input processor will substitute it for the current contents of the Job or SDF-P variable.
Examples:
*001 FILE=&(SELSTR);SHARE=N;VAR=ON&/CAT RDPASS=&(PASSW),STATE=U
*001 VOLUME=PUBLIC;AGE=0;VAR=ON&MOVE &(CFS.VOLUME)/D3480
The enhanced procedure mode allows all kinds of file processing, as well as the ability to create and control Connections from a procedure. This mode provides the full functional scope of CFS in procedure mode. This is achieved by trapping all WRTRD calls (screen input requests) and supplying the input from SYSDTA records. The screen message headers are managed by CFS itself.
CFS behaves in enhanced procedure mode in exactly the same way as it does for the user in dialog mode. This means that the procedure must be created with very careful regard to the program flow. Unforeseen CFS requests, such as whether or not a a file should be overwritten will affect the normal program run. The NQx command can be used to suppress any queries from the outset.
Terminating CFS in enhanced procedure mode is achieved in the same way as under dialog. There is no single, unique terminating condition. Instead, the different ways to terminate it are based on the situation that the program is in at the time. The END command can be used (* cannot be used, since it would be interpreted as a remark), or the CFS termination query can be answered with T (Terminate).
The task switch 11 may not be set if the enhanced procedure mode is to be used. In contrast to the basic procedure mode, the keyword records for file selection must have a *002 header. This causes CFS to accept the following commands and mask input from SYSDTA. The *002 records have the same format as *001 records.
Format of *002 Records
*002 select=par [; select=par ....... ; select=par ]
select Keyword, or abbreviation, for a selection mask field. CFS will substitute spaces as parameter values for those keywords not specified.
par Value for the respective Selection mask field.
Between a parameter value and another keyword, a semicolon is to be used as a separator character.
Only the first 80 bytes of each input record will be evaluated. If an input record is longer than 80 bytes, or if it is required to spread the record over many lines to help readability, a continuation character, "-", must appear in the last position. There is no limit on the number of continuation characters that may be used.
All input following a *002 record (commands and Connection input) will be passed directly to the program, i.e. without header. The next record to provide CFS with data for the Selection mask must be prefixed with the *002 header.
Notes:
*001 and *002 type records may not appear in the same CFS procedure, i.e. basic and enhanced procedure modes may not be mixed.
Enhanced procedure mode offers many additional procedure statements. These will discussed in detail later.
If &(jv-name) appears anywhere in a CFS procedure record, then CFS will substitute the current contents of the Job variable at that point.
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-.
All procedure-related language elements of CFS begin with an asterisk (*-statements).
.label Define a branch address for a *SKIP statement. The label designation can be up to 16 characters long. No other procedure statements or CFS commands may appear in a .label record.
Remark
*_[comment] Records consisting of only '*', or those beginning with '*' and followed by at least one blank, will be treated as remarks by CFS. They may be used to document the procedure.
" ... " Remarks can appear in the same record as procedure statements. For them to do so, they must be enclosed in quotes.
Example: *&PTR=&PTR+1 "Increment pointer by 1"
Note:
An asterisk cannot be used in procedures as a command to terminate CFS, since it will be interpreted as a remark. Terminating CFS from within a procedure is only possible using the END command, or by answering the termination query with 'T'.
A BS2000 command cmd will be executed. Optional parameters can be used to enhance the command. Both cmd as well as param can contain CFS variables.
The messages or error messages displayed by the command can be queried by means of the CMDMSG variable, which is an internal CFS variable.
Example:
*&NAME='$CFS.CFS'
*/FSTAT &NAME
*WRITE '>&CMDMSG<'
Note:
The command * cannot be used to terminate CFS in procedures, since '*' is interpreted as a comment. Terminating the program from within a procedure is only possible by means of the END command, or by entering 'T' at the termination acknowledgement stage.
Simulate Pressing a Data Transfer Function Key
*K1 | *K3 ... | *K14 | *F1 | ... | *F5 | *DUE1
Pressing a K, F, or DUE key is simulated during the execution of the procedure. The K2 and DUE2 keys cannot be simulated. Regarding the K2 key, see the *ON %TIME procedure statement on page 19-.
Example:
*K1 ==> Pressing the K1 key will be simulated when the procedure is executed.
*&var1 = [ &var2 | [C|L|X]'string' ] [ .&var3 | .[C|L|X]'string' ] ...
The value following the '=' sign will be asigned to the procedure variable &var1. A procedure variable can also be assigned a value calculated by an aritmetical operation on two constants or other variables. The syntax of such a construction is described below.
&var2 &name [ ( [s] [, l] ) ]
Value or substring of a CFS procedure variable.
&name Name of a CFS procedure variable or %PTR.
%PTR can be used with regard to positions of search string results returned by previous *IF %OUT=... or *ON %OUT=... statements.
%PTR(1,l) represents, for example, a string that is l byte long, occuring after the string found with the %OUT string. For a full example of the usage of %PTR, see page 19-.
%PTR0(1,l) represents the first byte of the search string, or the first byte of the first of a sequence of search strings linked with *.
s optional specification of the start column for a substring of the variable. ( 1 <= s < 80 ). Negative columns can also be specified for %PTR.
%PTR(s,l) indicates a string l bytes long, beginning at position s-1 behind that position at which the string found by %OUT begins.
%PTR(-s,l) indicates a string l bytes long, beginning s positions before the string found by %OUT.
Standard: s = 1.
Example:
Text to be searched: 123abc---------xyz789
*IF %OUT='abc'*'xyz'
*&VAR=%PTR(1,3) --> &VAR='789'
*&VAR=%PTR(-3,4) --> &VAR='-xyz'
*&VAR=%PTR0(1,4) --> &VAR='abc-'
*&VAR=%PTR0(-3,4) --> &VAR='123a'
l optional specification of the substring length. ( 1 <= l <= 80 ).
Standard: l = Full length of the variable.
[C|L|X]'string' constant string. C'string' is equivalent to 'string'. L'string' will result in the lowercase letters in string not being converted to uppercase. Apostrophes within a string must be entered twice ('').
If the variable is assigned a numerical value, the apostrophes can be omitted: *&var=[-]num
Examples: *&N=1, *&COUNTER=-10
.&var3 Multiple substrings can be suffixed to the variable in the form .&var | .'string'. A fullstop must be specified as a separator before the second and later substrings.
Notes:
The name of a procedure variable that has not yet been declared can be specified for &var1. The variable will automatically be created, and can be used immediately.
A Procedure variable can also be assigned a value captured from a Display file. For further information, see the W (Write) command on page 8- and the S,..=W command (Search and Rewrite) on page 8-.
*&var1 = [ &var2 | value ] op [ &var3 | value ]
The result of the arithmetical calculation following the '=' sign will be assigned to &var1.
&var2 | &var3 Name of a CFS Procedure variable.
value numerical constant: [-] number.
op arithmetical operator:
+ | - | * | /
Notes:
The *RUN procedure statement can be used to perform complex operations, perhaps also including search conditions, on procedure variables. For further information, see page 19-.
If procedure variables are specified as arithmetical operands, these must contain numerical values ([-]number). An exception is the CFS-internal variable &DATE (yy-mm-dd). &DATE can be arithmetically linked by + or - to a numeric constant. The result is still a date.
If two values are divided, the result will be rounded. If an attempt is made to divide by zero, then the &var1 variable will not be assigned a value (equivalent to &var1='').
Examples:
*&T1='Connection 1: Application '
The specified character string will be assigned to variable &T1.
*IF &CON1 = '' &T1 = &T1.' not opened'
If Connection 1 has not been opened (contents of variable &CON1 = ''), the character string ' not opened' and the previous value of the variable &T1 will be concatenated.
*IF &CON1 -= '' &T1 = &T1.&CON1
If the CFS-internal variable &CON1 is not empty (''), i.e. if Connection 1 has been opened, then &T1 and &CON1 will be concatenated.
*&DZ = &DATE(7,2).'.'.&DATE(4,2).'.' .&DATE(1,2).' '
*&DZ = &DZ.&TIME(1,2).':'.&TIME(3,2).':'.&TIME(5,2)
A new variable &DZ will be constructed from the CFS-internal variables &DATE (yy-mm-dd) and &TIME (hhmmss), which will contain the following: 'dd.mm.yy hh:mm:ss'.
*&COUNT=&VAR1+1
The value in &VAR1 will be incremented by 1 and assigned to &COUNT.
*&VAR1=&VAR1-&N
The value in &VAR will be decremented by the value in &N.
*&D=&DATE+1
The variable &D will be assigned tomorrows date (dd-mm-yy).
Further examples can be found on page 20-.
Assign the Input Source to SYSCMD
*CON SYSCMD The *CON statement is only relevant in Startup files, and will result in the next input being read from SYSCMD. It is thus possible to call CFS from a DO procedure, and run the normal CFS Startup (no /SETSW ON=(1,14) in the DO procedure). At the end of the procedure, the input source can be switched to the DO procedure with a *CON statement. This means that further special commands can be executed in addition to the general Startup commands.
If CFS is not called from a DO procedure (Procedure Level 0), then the *CON SYSCMD statement will have the same effect as the *DIA statement (see below).
A terminating statement (*ON %END CONTINUE) will be correctly handled if it follows a *CON statement.
*DIA [cmd] The *DIA statement will result in all subsequent input being requested from the user, i.e the input medium is returned to the keyboard.
cmd If cmd is specified, that command will be executed before control is returned to the user. Any CFS or BS2000 command can be specified.
In a procedure-controlled EDT dialog, it is recommended that the K3 key be simulated in order to refresh the screen before switching control back to the user (*K3 statement).
Examples:
*DIA /SYSFILE SYSDTA=(PRIMARY)
*DIA ^ (Return from a Connection to the main task).
*DIA RES CFS.LOG.xxx
*EXIT This statement terminates the procedure. No further procedure statements will be processed. This statement can appear at any stage in the procedure, and ends any further processing.
Normally, a procedure is ended following the processing of the last statement. A *DIA statement does not terminate the procedure. Instead, control is passed to the user. The procedure can be continued by issuing a RET command, or by a latent ON condition being satisfied (see page 19-).
Example:
*IF &N=0 EXIT
The procedure will be terminated if the variable contains the value 0.
2 different *IF statement formats are described below. *IF will result in a branch within the procedure if a condition is fulfilled.
*IF &[&]var1 op [ [C|L|X] 'string' | &[&]var2 ] cmd
The contents of the variable &var1 is compared with the value of the character string enclosed in quotes, or with the contents of the procedure variable &var2.
&var1 | &var2
&name [ ( [s] [, l] ) ]
Name of a procedure variable or a substring of a variable.
s optional specification of the start column for the substring of the procedure variable. ( 1 <= s < 80 ).
Standard: s = 1.
l specification of the length of the procedure variable substring. ( 1 <= l <= 80 ).
The special characters * or $ can be used in the first comparison operand (&var1) for l. The exact usage of these characters is described in detail in a later section.
Standard: l = Total length of the variable.
Examples:
&FILE(4) Contents of the variable &FILE, from column 4 to the end of the variable
&FILE(4,20) Contents of the variable &FILE, from column 4 for a length of 20
&FILE(,20) Contents of the variable &FILE, from column 1 for a length of 20
&&var1 | &&var2
The contents of the variables &var1 | &var2 will be regarded as the name of another variable whose contents should then be evaluated.
Example: &NA='CON1'. Specifying &&NA will evaluate the contents of the CFS-internal variable &CON1. Another example of double substitution can be found on page 20-.
op Comparison operator: [-] { > | < | = }
If the alphanumeric comparison of greater than (>) / less than (<) / equal to (=) is true / false (-), then the command specified as cmd will be executed.
[C|L|X]'string' constant character string. Any single quotation marks appearing in the string must be entered twice ('').
The contents of the variable to the left of the equality sign or the partial string will be compared with the specified constant. Equality will only be flagged if the respective lengths match as well as the contents. Null characters not contained in the constant will result in the values not being declared equal. For further information, see the following section.
If string contains pure numerical values, the quotes can be omitted.
Examples: *IF &N=1, *&COUNTER>-10
cmd any CFS procedure language statement. The standard asterisk that prefixes a statement must not be included.
The characters * or $ have special meanings when comparing to constants
* Only compare the length of the variable to the left of the equality sign with that of the constant on the right. Additional characters in the variable will be ignored. &VAR(,*) can be abbreviated to &VAR(*).
$ Expand the constant to the right of the equality sign until the string returns the same length as the variable with which it must be compared.
&VAR(,$) can be abbreviated to &VAR($).
Examples:
*IF &FILE(,*)='ABC' SKIP .ABC or in abbreviated format:
*IF &FILE(*)='ABC' SKIP .ABC
The first three characters of the variable &FILE will be compared with the constant 'ABC', and if equal, a jump to label .ABC will be executed.
*IF &FILE(25,*)=' ' SKIP .A25
The contents of the variable &FILE will be compared from column 25 for a length of 1 byte with the constant '_' . If they are equal, a junp to label .A25 will be executed.
*IF &FILE(,$)=' ' SKIP .A27 or in abbreviated form:
*IF &FILE($)=' ' SKIP .A27
The total contents of the variable &FILE will be compared with an equal number of null characters. If &FILE consists only of null characters, a jump to label .A27 will be executed.
*IF &FILE(25,$)=' ' SKIP .A25
A check will be made to determine whether the variable &FILE contains null characters (at least one) from column 25 on. If so, a jump to label .A25 will be executed.
Note:
When comparing a procedure variable with a constant or with a second procedure variable, case is not normally taken into account. The statement *SET CASE=Y can be issued to force a case check.
Examples:
*IF &FIL='' PROMPT &FIL,'Please enter filename '
If the &FIL variable is empty, the user will be requested to enter a value via the *PROMPT statement.
*IF &FIL=&D2 SKIP .SAME
If the value of the &DAT variable is equal to that of the &D2 variable, then a branch will be made to the label ".SAME".
*IF &COUNTER>9 EXIT
The procedure will be terminated if the &COUNTER variable has a value greater than 9
Further examples for the assignment of variables can be found on page 20-.
*IF SETSW [ON|OFF]=n cmd
The task switch n will be tested. If the tested switch condition is true, the specified command, cmd, will be executed.
cmd any CFS procedure language statement. The standard asterisk that prefixes statements must not be included.
Notes:
The task switch 31 is used by CFS to indicate errors. If, for example, no data objects matching the specification are found during a selection operation, this switch will be set. In procedure-controlled mode, this case will be treated as if FILENAME-SELECT : NO was specified in the Selection mask. The second mask will be displayed, where only the COMMAND field will be displayed. In non-procedure mode, the Selection mask will be displayed with the respective error message.
Task switch 31 will also be set if any errors are encountered during ONXCOPY/ ONXSEL/ ONXADD Variable Actions.
If task switch 31 is to be checked in a procedure, it should always be reset before any CFS action which may alter its state. (Command /SETSW OFF=31).
The *IF %OUT condition is satisfied if the search string is found in the WRTRD output segment. If this is the case, the command specified, cmd, will be executed. In addition, a pointer, %PTR, will be set to the end of the search string found in the output text. The pointer can then be used to assign a substring to a procedure variable.
Example: *IF %OUT=L'search item found and replaced' &COUNT=%PTR(1,7)
Specifying (1,7) after %PTR will be interpreted as offset and length operands for the assignment of a procedure variable. An offset of 1 flags the first position after the last search item column.
(%PTR) Following an *IF %OUT statement, a search will be made in the output text for the string specified in srch, as from the column in which the last search argument was found.
srch single or multiple search argument in the format 'string' | L'string' | A'string' | X'string'.
It should be noted when entering a search string in the form 'string' that lowercase letters will be converted to uppercase.
If L'string' is specified, no case conversion will take place.
If A'string' (Any) is specified, the case of both the search string entered, as well as the text being searched, is irrelevant, with all text being converted to uppercase before the comparison.
Multiple search arguments can be entered, linked with + (AND) / , (OR) / * (Wildcard) operators.
cmd CFS procedure language statement. The asterisk that normally prefixes procedure statements must not be included.
A full description of the search statements can be found on pages 8- and 8-.
Example:
The following procedure will prevent the user from reaching the CFS Selection mask by pressing the K1 key. Refer to page 19- for information regarding the ON %OUT statement.
.ON-IN
*ON %IN=K1 SKIP .TEST-MASK The mask contents following K1 are tested
*DIA
*EXIT
.TEST-MASK
*IF %OUT='FILENAME-SELECT :' SKIP .INPUT-NO
*SKIP .ON-IN
.INPUT-NO
NO
*SKIP .ON-IN
Load Procedure Variables from a File
file The names and values of CFS procedure variables will be read from the specified name, and enabled for the current procedure. The variables can then be treated exacly as if they had been assigned with a *&var='value' statement.
C Clear. All variables created previously by the procedure will be erased before executing the *LV statement. Thereafter, only those variables stored in the LV file will be available.
O Overwrite. Variables previously created in the procedure will continue to be available after the execution of the *LV statement. Variables created in the procedure before the execution of the *LV statement with an identical name to those in the LV file will be overwritten by the LV file values.
Standard: If neither of the C|O options are specified, identically-named variables will not be overwritten by the LV file contents.
Define Events for Latent Conditions
9 different variations of the ON condition are described in the following section.
The *DIA procedure statement can be used to interrupt the procedure, and pass control to the user. In this case, the only user command to restart the procedure manually is the RET command. See page 19-.
ON statements can be used to restart the procedure automatically, based on certain conditions being met. ON statements must be specified before a *DIA statement (switch to user input) is encountered. Latent conditions are defined such that each user input will be checked by CFS to see if an ON condition has been fulfilled. If so, the procedure will be restarted automatically.
*ON %ABEND CONTINUE | SKIP .label
*ON %ABEND is satisfied when CFS is terminated abnormally. This will be the case, for example, if the communications line is lost, or if an /EXEC, /LOAD, /DO, /CALL, or /LOGOFF command is entered in BS2000 command mode with CFS still loaded. When the %ABEND condition is encountered, the procedure controlled mode will be activated, and the action specified in the statement will be carried out.
CONTINUE The procedure will restart at the point at which it was interrupted by the last *DIA statement.
SKIP .label The procedure will be restarted at the specified label, and processing will be continued from there.
*ON %CMD CONTINUE [AFTER INPUT] | SKIP [AFTER INPUT] .label
After the user has taken control of the procedure, CFS will check each input to see if it is a command. If so, the *ON %CMD condition will have been satisfied, and the action in the ON statement will be carried out.
CONTINUE The procedure will be restarted automatically before the first CFS command field input step.
CONTINUE AFTER INPUT
The procedure will be restarted automatically after the first CFS command field input (e.g. even sending an empty CFS mask).
SKIP .label The procedure will be restarted automatically with the first CFS command field input at the specified label.
SKIP AFTER INPUT .label
The procedure will be restarted automatically after the first CFS command field input at the specified label.
Example:
The following procedure opens a connection to $CONSOLE. After returning to the main task of CFS, the Connection will be closed automatically. (*ON %CMD CONTINUE).
OC9$CONSOLE
xxxxx,C'sssss'
*ON %CMD CONTINUE
*DIA
DC9
*ON %END CONTINUE | SKIP .label
*ON %END will be satisfied when the user requests CFS to be terminated (*/END commands, K1 key). When the %END condition has been satisfied, the procedure will be restarted automatically, and the action specified in the ON statement will be carried out.
CONTINUE The procedure will be restarted automatically at the point at which it was interrupted by the last *DIA statement.
SKIP .label The procedure will be restarted automatically at the specified label.
Notes:
The *ON %END condition will also be satisfied if CFS is terminated by a /LOGOFF, /DO, /CALL, /EXEC, or /LOAD command. The execution of the specified command will be delayed by CFS until all commands in the termination routine have been processed, after which the relevant BS2000 command will be processed.
The *ON %END condition will not be fulfilled if CFS is terminated abnormally (see *ON %ABEND statement described earlier). The *ON %END statement is also not satisfied if CFS is terminated in procedure controlled mode by an END command, or by answering T to the termination query.
From the above it can be seen that an END command specified within the *ON %END command sequence will lead to the unconditional termination of CFS.
The *ON %END statement can be used to initiate a command sequence to terminate CFS (CFS Shutdown). This command sequence is the logical counterpart to a CFS Startup file. This could be used, for example, to close all opened Connections in a controlled manner. In addition, it can be used to save the command memory to a file or library.
An example of the *ON %END statement can be found in Chapter 20 "Startup".
*ON %IN= { key | srch } CONTINUE | SKIP .label
key Key designation: K1, K3, ... , K23 / F1, ... , F20 / DUE1 / DUE2
This variation of the %IN condition will be satisfied after the user has pressed the specified data transfer key. The procedure will be restarted automatically, either at the point of interruption (CONTINUE), or at the specifed label (SKIP .label).
srch single or multiple search argument in the form 'string' | L'string' | A'string' | X'string'.
It should be noted when entering a search string in the form 'string' that lowercase letters will be converted to uppercase.
Entering L'string' will retain the letters in their original case, with no conversion taking place.
If A'string' (Any) is specified, the case of both the search string entered, as well as the text being searched, is irrelevant, with all text being converted to uppercase before the comparison.
Multiple search arguments can be linked by the + (AND) / , (OR) / * (Wildcard) operators.
The %IN condition is fulfilled when the search string(s) is/are contained within the input entered by the user. The procedure will be restarted at the point of interruption (CONTINUE), or a branch made to the specified label. In addition, a pointer, %PTR, will be set to the end of the search string that occurred last. The pointer can be used to assign a substring from the user input to a procedure variable. For further information, see page 19-.
For a full description of search conditions, see pages 8-/8-.
*ON %IN The last defined *ON %IN condition is reactivated.
An example of the ON %IN statement can be found on page 19-.
*ON %INP will be satisfied after the first user input, following control being switched to the user with a *DIA statement. When the %INP condition has been fulfilled, the procedure will be restarted. (CONTINUE).
Notes:
The *ON %INP condition can be used to allow the user to make a single entry during the execution of the procedure (for example in EDT or in a Connection), and then to have the procedure continue automatically.
Further procedure statements can occur after the *ON %INP, since the %INP is only activated after a *DIA (switch to user entry) statement.
Example:
*002 FILE=NO
EDT
READ'file'
LOWER ON
*WRITESYS 'Please make amendments. Procedure will then continue automatically'
*ON %INP CONTINUE
*F2 F2 key: Make EDT screen overwritable
*K3 K3 key: Refresh screen
*DIA
WRITE'file'
HALT
END
*ON %LST CONTINUE [AFTER INPUT] | SKIP [AFTER INPUT] .label
After control has switched to the user following a *DIA statement, CFS will check each dialog step to see if the user input has caused a switch from Display to List mode (achieved either by pressing the K1 key, or by entering a LST command). If this is the case, the *ON %LST command is satisfied, and the action specified in the ON statement will be carried out.
CONTINUE The procedure will be restarted automatically before the first command in List mode.
CONTINUE AFTER INPUT
The procedure will be restarted automatically after the first command in List mode entered by the user.
SKIP .label The procedure will be restarted automatically before the first command in List mode (display the file list), at the specified label.
SKIP AFTER INPUT .label
The procedure will be restarted automatically after the command entered by the user in List mode, at the specified label.
*ON %OUT=srch CONTINUE [AFTER INPUT] | SKIP [AFTER INPUT] .label | RETURN | RESUME
srch single or multiple search argument in the form 'string' | L'string' | A'string' | X'string'.
It should be noted when entering a search string in the form 'string' that lowercase letters will be converted to uppercase.
Entering L'string' will retain the letters in their original case, with no conversion taking place.
If A'string' (Any) is specified, the case of both the search string entered, as well as the text being searched, is irrelevant, with all text being converted to uppercase before the comparison.
Multiple search arguments can be linked with one another by + (AND) / , (OR) / * (Wildcard) operators, and can be stored as a file or library element (*ON %OUT=(file) ...). An example can be found on page 19-.
The %OUT condition is satisfied when the search string(s) is/are contained in the output message (WROUT or the output section of a WRTRD). In this case, a pointer, %PTR, will be set to the end of the search string in the output message. The pointer can be used to assign a substring of the output message to a procedure variable. For further information, see page 19-.
CONTINUE The procedure will be restarted. If a WROUT call was made, the next input will be made by the procedure. If a WRTRD call was made, that input requested by the call will be provided by the procedure.
CONTINUE AFTER INPUT
The procedure will be restarted after the user has entered the input for the current WRTRD.
SKIP .label The procedure will be restarted at the specified label.
SKIP AFTER INPUT .label
The procedure will be restarted automatically, after the user has entered the input for the current WRTRD, at the specified label.
RETURN The user will be returned from a Connection to the main CFS task (command field).
RESUME When the condition has been satisfied, the procedure will be restarted, even if there is no user input at that moment. The ability to resume the execution of a procedure without user input is particularly useful for Connections to $CONSOLE.
*ON %OUT The last *ON %OUT condition to have been defined will be reactivated. The evaluation of the search conditions will not take place.
A full description of the search conditions can be found on pages 8- and 8-.
*ON %TERM CONTINUE | SKIP .label
After control of the procedure has passed to the user, CFS will check each user input to see if it fulfills the termination query of CFS (TERM / NEW / UPDATED FILE-LIST ...). If so, the *ON %TERM condition is satisfied, and the action specified in the ON condition will be carried out.
CONTINUE The procedure will be restarted automatically at the point at which the termination query was answered. The termination query answer must be taken into account by the procedure.
SKIP .label The procedure will be restarted automatically at the specified label. The termination query answer must be taken into account by the procedure.
This condition invokes a timer for a specified time, after which CFS will pass control from a Connection back to the main task (command field). This makes it possible to return to CFS from an "active" Connection, even though nothing was entered from the Connection. Thus, CFS can regain control from programs with asynchronous output, such as $CONSOLE.
s Elapsed time in seconds (0 <= s <= 9999).
Examples:
The following procedure establishes a Connection to $CONSOLE, then issues a /STA MSG command, and then a /STA P command. On returning to the main task with K2 + R, the Connection will shut down automatically.
OC9$CONSOLE,,,R R: Return switch. CFS switches back to the main task after
successfully opening the Connection.
xxxxx,C'sssss' Enter the userid and password after returning from the
CC9B Connection: K2 for the Console
*ON %TIME=1 RETURN Define condition: return from the Connection to the main
task of CFS after 1 second.
STA MSG Console input
CC9B After returning to the main task (*ON %TIME=1):
regenerate K2 for the console
*ON %TIME=1 RETURN Reinitialise return timer.
STA P Console input
*ON %CMD CONTINUE Define condition: after returning to the main task, the
procedure should be continued automatically.
*DIA Switch the input source to user dialog
DC9 After returning to the main task by means of the user
pressing K2 + R, procedure mode will be resumed, and the
Connection will be terminated by DC9.
A Connection is tp be established to the host system VAR2, under the TSOS userid. Statistics for system performance analysis are to be collected using the SM2 program. A DO procedure to achieve this could look as follows:
/PROC N
/SYSFILE SYSDTA=(SYSCMD)
/SETSW ON=(1,4)
/EXEC $CFS
*002 FILE=NO
OC1,,VAR2/LOGON TSOS,...
EXEC $SM2
*ON %TIME=10 RETURN After 10 seconds the procedure will switch back to the main
CFS task.
HC SM2.STATISTICS,N All following output will be captured to the hardcopy specified
file.
START Start the SM2 statistic output. The statistical information
will be displayed in 120 second intervals.
Since only the first display is of interest, an exit will be
made from the Connection after 10 seconds. This allows new CFS
commands to be entered.
CC1B Switch to Connection 1 by simulating the K2 key. This will
suppress further SM2 statistic output.
NHC Switch off hardcopy mode.
LOGOFF Close the Connection.
END Terminate CFS.
/SETSW OFF=(1,4)
/ENDP
*PROC Statement - General Remarks
If a *PROC statement is present (see below for syntax), the following additional functions are available:
1) When the procedure is called, CFS first analyses the PROC statement, and displays a mask with all defined parameters, together with their predefined values (keyword parameters). This mask is identical to that displayed when starting a BS2000 DO procedure in Enter mode (see page 11-).
This parameter mask can be suppressed by starting the procedure as follows: DO N,procedure,... . Here, N means No Prompt for Parameters.
2) If specified in the PROC statement (*PROC x,....), the logging scope can be determined for the procedure run, as in BS2000 DO procedures.
If a *PROC statement is not present in the procedure, then the following points should be noted by both the procedure author, and the user:
1) The procedure statements and data records will not be logged (*PROC N).
2) The mask for entering parameter values cannot be displayed. All variables that are to have a predefined value must either be specified in the DO command as positional or as keyword parameters, or should be requested from the user during the procedure by means of a *PROMPT statement.
3) With regard to assigning the procedure variables from parameters at procedure call time, the procedure author must take note of the following:
The first positional parameter specified when calling the procedure can only be assigned to the variable name &1. Likewise, the second as &2, and so on.
*PROC Statement Syntax (Format 1)
*PROC x, (par, [" text "] ... )
The *PROC statement syntax is identical to that used in BS2000 DO procedures. The only thing missing in the *PROC statement is the SUBDTA parameter. Any number of continuation lines are possible. A hyphen (-) may appear at any point in the statement as a continuation character. In contrast to BS2000 procedures, a continuation line begins with '*', and not with '/'. Remarks enclosed in quotes (".....") can appear anywhere in the line. These remarks have a special function in the parameter mask when calling the procedure (see below).
The PROC statement in Format 1 must be the first statement in the procedure.
The individual PROC statement elements are described below:
x A | C | D | N
Control the logging scope of the procedure.
A All procedure statements, as well as all data records passed to CFS, will be displayed on the screen.
C Only the procedure statements (* statements) will be displayed on the screen.
D Only the data records passed to CFS will be displayed on the screen.
N Neither procedure statements nor data records will be displayed on the screen (Default).
par &var | &var=value
Establish procedure parameters (positional or keyword parameters).
&var A positional parameter is established for the procedure. A positional parameter has no predefined value. The value specified by the user for &var when calling the procedure can be used within the procedure.
&var=value A keyword parameter is established for the procedure. A keyword parameter can contain a predefined value. This predefined value of a keyword parameter can be amended when calling the procedure, by specifying var=value.
value Predefined value for the keyword parameter. value can be specified with or without quotes. If it contains special characters such as blanks, then it must be enclosed in quotes.
"text" The text specified here will be displayed in the parameter mask as 'var text...'. var is the name of the variable, and text is a description of the variable, possibly together with permissable values. The total length of var and text is restricted to 30 bytes.
By default, each procedure parameter will have one line reserved for it in the mask. This means that parameter values may normally not exceed 40 bytes. By specifying #n (n < 4), one to three additional input fields, each 40 bytes long, may be reserved. #n must be specified after the first " or ": .
Example: If the PROC statement contains a line as follows: /&FILE=TEST, ":#3Name of the file to be processed",
then this DO parameter will be displayed in the mask as follows:
Name of the file to be processed =TEST
:
:
:
":text" The text specified here will be displayed as 'text...' in the parameter mask when the DO procedure is called. The variable name will not be displayed. text is a description of the variable, possibly together with permissable values. The total length of text is restricted to 30 bytes.
If no descriptive text is specified for a parameter, the parameter will be displayed in the mask as 'var '.
*PROC Statement Syntax (Format 2)
*PROC x This format is only used for setting or amending the logging mode. A Format 2 *PROC statement may appear many times within the procedure, and does not have to be the first statement in the procedure. This is true even if the procedure begins with a Format 1 *PROC statement.
x A | C | D | N
Control the logging scope during the procedure.
A All procedure statements, as well as all data records passed to CFS will be displayed.
C Only the procedure statements (* statements) will be displayed.
D Only the data records passed to CFS will be displayed.
N Neither procedure statements nor data records will be displayed (Default).
Example:
The CFS procedure S/O in the CFS.USERLIB contains the following statements:
*PROC N,(&1, ":Conn.Nr. to be opened" - * &VAR=2, ":Host system <1/2>" - * &JOBNAME=FRANK, ":Jobname for LOGON" - * &USER-ID=XYZ, ":Userid for LOGON" - * &ACCOUNT=I001, ":Account number" - * &PASSW='C''...''' ":LOGON password") *IF &1 = '' &1 = &NEXTCON OC&1,,VAR&VAR/.&JOBNAME.&1 LOGON &USER-ID,&ACCOUNT,&PASSW *WRITESYS 'Conn. &1 under &USER-ID opened (&JOBNAME)'
The following mask will be displayed after entering DO O:
} dd.mm.yy hh:mm:ss J O B - R E P O R T TSN: .... {
} COMMAND :DO CFS.USERLIB(O) {
} {
} D O - P A R A M S {
} Conn. Nr. to be opened : {
} Host system <1/2> =2 {
} Jobname for LOGON =FRANK {
} Userid for LOGON =XYZ {
} Account number =I001 {
} LOGON password ='C''...''' {
} {
} {
} {
} {
}You may now complete the DO-Params. (Cancel with K1){
Prompt for Procedure Variable Value
*PROMPT &var [, 'text'] [,L] [D]
The user will be prompted for the value for the procedure variable &var.
&var Name of the procedure variable to be assigned the value entered by the user.
text Text for the prompt.
If no text is specified in the PROMPT statement, '&VAR=' will be displayed as the prompt.
L The text for the &var variable will not be converted to uppercase.
Standard: The text will be converted to uppercase.
D The text for the &var variable will not be displayed i.e the field is dark.
Standard: The text in response to the PROMPT statement is visible.
*RESET [%ABEND | %CMD | %END | %IN | %OUT | %LST | %TERM | %TIME]
This statement resets a previously defined ON condition. The RESET statement is necessary if an ON condition is to be reset, even though it has not yet occurred. When the ON condition occurs, it is reset automatically. ON conditions belonging to a particular category (%LST, %CMD, %TERM, %TIME, %END) can only be specifically enabled once.
If no conditions are specified, all latent conditions will be reset.
Note:
The following ON conditions defined in a Startup file, or from a running procedure, will be reset automatically when a procedure is called: ON %CMD / %IN / %OUT / %LST / %TERM. The ON %ABEND and ON %END conditions defined in a Startup file remain active even after calling a CFS procedure.
Amend Procedure Variables using FHS
*RDMASK (format [,lib] ) [TAR=n,] [&var1, &var2, ... ]
The *RDMASK statement will display an FHS *-format mask, in which the contents of the specified procedure variables will be displayed in the various fields of the FHS mask. After transmitting the mask with DUE1 or ENTER, the contents of the modified fields will be assigned to the procedure variables. The contents of the first field will be assigned to the first procedure variable specified, and so on.
format Name of the FHS mask in the CFSLIB.
(format,lib) Name of the FHS mask in the specified format library.
TAR=n Tabulator Right. When the mask is displayed, the cursor will normally be positioned in the first input field (TAR=0). The parameter TAR=n (n = 1, 2, ...) enables the cursor to be positioned in the second (TAR=1), third (TAR=2) etc. entry field.
Normally, the parameter can be omitted.
&var1 Name of the procedure variable to be assigned the contents of the first mask field.
If the variable does not yet exist, it will be created by CFS as an empty variable. The data portion of the CFS procedure variable must not exceed 80 bytes. Longer mask fields will be truncated when being transferred to the variable.
When displaying the mask, the current contents of the procedure variables will be displayed in their respective mask fields.
If more variable fields exist in the mask than procedure variables, then the entries in the surplus fields will be lost.
Notes:
With the exception of &CFSMSG, no other CFS-internal variables, such as &DATE or &TIME may be specified.
The MFHSROUT library must be assigned with a file command before the first *RDMASK statement, as follows: /FILE lib,LINK=MROUTLIB
Only *-format FHS masks can be displayed with the *RDMASK stetement. If IFG was used to create an FHS * format mask, the following points should be noted:
In the "DEFAULT VALUES FOR APPLICATION PREPARATION, ADDRESSING AID SPECIFICATIONS" screen, the following entries are necessary in the "Structure of the data transfer area":
separate attribute blocks and field contents : NO
aligned, with attribute fields : NO
unaligned, with attribute fields : NO
unaligned, without attribute fields : YES
The relative entries are also necessary when defining the formats using FHS macros.
The *RDMASK statement can also be used merely to display an FHS mask in a CFS procedure: *RDMASK (format,lib)
Within the procedure, the *RDMASK statement can be split across many lines. A hyphen should be used as the continuation character, with an asterisk appearing as the first character of a continued line.
Return Command Input to SYSCMD
*RET SYSCMD The *RET statement is meaningful if CFS is called from a BS2000 DO procedure and which then calls multiple CFS procedures one after the other by means of DO commands.
Example:
*002 FILE=NO
DO CFS.USERLIB(PROC1)
DO CFS.USERLIB(PROC2)
DO CFS.USERLIB(PROC3)
END
In order for the sequence of procedures to function as expected, each of the CFS procedures (PROC1 to PROC3) must have a *RET SYSCMD command as their final statement. This will result in the command input source being redirected from SYSDTA (i.e. from the current CFS procedure file) to the BS2000 procedure. The next CFS DO command will then be read and executed.
If CFS is not invoked from a DO procedure (Procedure Level Number 0), then the *RET SYSCMD statement will have the same effect as the *DIA statement (see below).
Return to the Procedure from Dialog
This command, entered in the COMMAND field, switches the input medium from the keyboard to SYSDTA. From this point on, CFS will run in procedure-controlled mode. The RET command is the counterpart to the *DIA procedure statement.
file | lib(element) Specifying a parameter with the RET command will reassign the input source for SYSDTA before switching back to procedure mode as follows: SYSFILE SYSDTA=file | SYSFILE SYSDTA=lib (element).
If lib(element) is specified, the CFS procedure to be executed is determined explicitly. Otherwise, CFS first searches the specified userlib (Default: CFS.USERLIB) for an element with the specified name. If no such element exists in the userlib, then a file of that name will be sought. To amend the standard CFS userlib, see the UL command on page 18-.
Resuming a procedure automatically when certain contextual conditions have been met can be achieved with the *ON procedure statement:
*ON [%END | %TERM | %ABEND | %CMD | %LST | %IN | %OUT | %INP].
The Run statement allows contents of CFS procedure variables (no internal variables) to be evaluated in different ways and then modified or converted to a different format. The Run statement accesses different program modules which can perform a number of different individual functions. The number of modules is constantly being extended. In addition, new sub-functions are being added to existing modules.
In order to modify the contents of a CFS variable with a Run statement, the variable must first be loaded with user-specific data. This variable can then be modified or evaluated with a Run statement.
Call format of the Run Statement
*RUN (module [,lib] ) [param,] [&var1, &var2, ... ]
The *RUN statement calls a user subprogram.
module Name of the user module in CFSLIB.
(module,lib) The user module is stored in the specified library.
param Parameters to be evaluated by the user module.
&var1 Name of the first CFS procedure variable to have been passed to the procedure.
If the variable does not yet exist, it will be created by CFS as an empty variable. The user module has access to this variable, and can modify its contents.
The name of the variables can also be specified in the form &&var. In this case &var contains the name of the variable to be processed in the data.
Apart from &CFSMSG and &SLABEL, no other CFS-internal variables, such as &DATE or &TIME may be specified. The *RUN statement can be split over many lines within the procedure. A hyphen should be used as a continuation character, and an asterisk should appear as the first character in a continuation line.
The following sections contain the description of all currently available Run modules, together with their respective sub-functions. Additionally, the published program interface allows the user to write customised Run modules. The program interface specification for Run modules is described at the end of the section.
*RUN (CPROMPT)&var1,&var2
The CPROMPT routine displays the text contained in &var1 (or text entered directly with (CPROMPT)'text' ) on the console with a TYPIO function. An acknowledgement in the form tsn.text is expected. The acknowledgement text will be returned in the &var2 variable. The routine remains in a wait state until the operator has answered the PAUSE message on the console.
*RUN (DATE) ...
The DATE routine offers various date calculation operations.
An operation code must be passed as the first parameter in which the required calculation or conversion is defined. The second parameter must contain the name of the procedure variable containing the input date. An optional parameter containing the name of another procedure variable can be specified, into which the result of the calculation/conversion will be returned. If a second procedure variable is not specified, the result is returned to the first variable.
A date can be specified in the input variable in the form ddmmyy[yy], dd.mm.yy[yy], dd-mm-yy[yy] or dd/mm/yy[yy] . If the result of the calculation is a date, it will be returned in the identical format to that of the input date.
*RUN (DATE){+|-}n,&invar [,&outvar]
The function +/- adds/subtracts n days to the date specified in &invar. The result is still a date. If an &outvar variable is specified, the result is stored in it, and the contents of &invar remain unaltered; otherwise the the result will be written to &invar. Errors are identified with the string 'ERR' .
Examples: *RUN (DATE)+7,&INDAT,&OUTDAT
&INDAT = '30.12.1993' --> &OUTDAT = '06.01.1994'
&INDAT = '301293' --> &OUTDAT = '060194'
&INDAT = '30121993' --> &OUTDAT = '06011994'
&INDAT = '32121993' --> &OUTDAT = 'ERR'
*RUN (DATE)-&invar1,&invar2 [,&outvar]
The function - returns the number of days between the date specified in the first variable (&invar1), and that specified in the second variable (&invar2). Both input variables must contain a date in one of the following formats: yy-mm-dd/yyyy-mm-dd/ dd.mm.yy/dd.mm.yyyy/ddmmyy/ddmmyyyy. The result will be returned to the output variable &outvar, if it is specified, and &invar2 will remain unaltered. If &outvar is not specified, the result will overwrite the original value in &invar2. An error is indicated by the string 'ERR'.
Example: *RUN (DATE)-&INDAT1,&INDAT2,&OUTVAR
&INDAT1 = '31.12.93'
&INDAT2 = '01.01.93'
--> &OUTVAR = '364'
*RUN (DATE)DW,&invar [,&outvar]
The DW function (Day of Week) returns the number of the day of the week for a specified date.
Example: *RUN (DATE)DW,&INDAT
&INDAT = '23.05.1994' --> '1' (Monday)
*RUN (DATE)DDD,&invar [,&outvar]
The DDD function returns the incremental day (Julian date) of the current year from the date specified in &invar in ddd format. Errors are identified with a 'ERR' string.
Example: *RUN (DATE)DDD,&INDAT,&OUTDAT
&INDAT = '23.05.1994' --> &OUTDAT = '143'
*RUN (DATE)FREE,&invar [,&outvar]
The FREE function returns a value 'Y' or 'N' if the date specified in &invar is or is not a holiday. Errors are identified with a 'ERR' string. Holidays are defined as Saturdays, Sundays, specified public holidays, and those days in the current year flagged in the IFREE file of the Event Handling System as holidays. For further information regarding the IFREE file, see page 14-.
Example: *RUN (DATE)FREE,&INDAT
&INDAT = '25.12.1994' --> 'Y' (Christmas Day)
*RUN (DATE)WD,&invar [,&outvar]
The WD function (Working Day) returns a value 'Y' or 'N' if the date specified &invar is, or is not, a workday. Errors are identified with a 'ERR' string. Workdays are defined as all those days in the year other than Saturdays, Sundays, specified public holidays, and those days flagged as holidays in the current year in the IFREE file of the Event Handling System. For further information regarding the IFREE file, see page 14-.
Examples: *RUN (DATE)WD,&INDAT
&INDAT = '01.01.1994' --> 'N' (New Years Day)
&INDAT = '24-05-94' --> 'Y'
*RUN (DATE)WDN,&invar [,&outvar]
The WDN function (Working Day Next) returns the date of the next working day, as from the date specified as the input date. Workdays are specified as all those in the year apart from Saturdays, Sundays, public holidays and those days in the current year flagged in the IFREE file of the Event Handling System as holidays. If the input date is on a working day, this date will returned as the result. For further information regarding the IFREE file, see page 14-.
Examples: *RUN (DATE)WDN,&INDAT,&OUTDAT
&INDAT = '23.05.1994' --> &OUTDAT = '24.05.1994'
&INDAT = '24/05/1994' --> &OUTDAT = '24/05/1994'
*RUN (DATE)WDP,&invar [,&outvar]
The WDP function (Working Day Previous) returns the date of the previous working day, as from the date specified as the input date. Workdays are specified as all those in the year apart from Saturdays, Sundays, public holidays and those days in the current year flagged in the IFREE file of the Event Handling System as holidays. If the input date is on a working day, this date will returned as the result. For further information regarding the IFREE file, see page 14-.
Example: *RUN (DATE)WDP,&INDAT,&OUTDAT
&INDAT = '23.05.1994' --> &OUTDAT = '20.05.1994'
*RUN (DATE)WDF,&invar [,&outvar]
The WDF function (Working Day First) returns the date of the first working day of a calendar month, that month being specified as the input date. Workdays are specified as all those in the year apart from Saturdays, Sundays, public holidays and those days in the current year flagged in the IFREE file of the Event Handling System as holidays. For further information regarding the IFREE file, see page 14-.
Example: *RUN (DATE)WDF,&INDAT,&OUTDAT
&INDAT = '05.1994' --> &OUTDAT = '02.05.1994'
*RUN (DATE)WDL,&invar [,&outvar]
The WDL function (Working Day Last) returns the date of the last working day of a calendar month, that month being specified as the input date. Workdays are specified as all those in the year apart from Saturdays, Sundays, public holidays and those days in the current year flagged in the IFREE file of the Event Handling System as holidays. For further information regarding the IFREE file, see page 14-.
Example: *RUN (DATE)WDL,&INDAT,&OUTDAT
&INDAT = '05.1994' --> &OUTDAT = '31.05.1994'
*RUN (DATE)WW,&invar [,&outvar]
Thw WW function returns the calendar week number of the year from the date specified in &invar (in ww format). If an &outvar variable is specified, the result is stored in it, and the contents of &invar remain unaltered; otherwise the the result will be written to &invar. Errors are identified with the string 'ERR' .
Examples: *RUN (DATE)WW,&INDAT
&INDAT = '23.05.1994' --> '20'
&INDAT = '01.01.1994' --> '0'
&INDAT = '03.01.1994' --> '1'
*RUN (DATE)WW1,&invar [,&outvar]
The WW1 function returns from the calendar week specified in &invar the date of the first day of this calendar week (Monday). If an &outvar variable is specified, the result is stored in it, and the contents of &invar remain unaltered; otherwise the the result will be written to &invar. Errors are identified with the string 'ERR' .
Example: *RUN (DATE)WW,&INDAT
&INDAT = '201994' --> '17.05.1994'
*RUN (DATE)VALID,&invar [,&outvar]
The VALID function checks the specified date for validity. The output variable will be set to 'Y' or 'N' depending on whether the input variable contains, or does not contain, a valid date.
Examples: *RUN (DATE)VALID,&INDAT,&RETCD
&INDAT = '30.12.1993' --> &RETCD = 'Y'
&INDAT = '301293' --> &RETCD = 'Y'
&INDAT = '30121993' --> &RETCD = 'Y'
&INDAT = '32121993' --> &RETCD = 'N'
&INDAT = '29.02.94' --> &RETCD = 'N'
*RUN (GETLEN)&var,&outvar
The GETLEN routine will return the length of &var to the output variable &outvar.
Example: *RUN (GETLEN)&VAR1,&VAR1LEN
&VAR1 = 'ABCD ' --> &VAR1LEN = '5'
*RUN (IFUQ)[noopt] [,label-1] ... [,label-n] ,&var-1, ... ,&var-n ,&skipvar
This routine enables a number of procedure variables to be tested for uniqueness. This is particularly important if the RDMASK statement is to be used. The RDMASK can be used to present the user with a list of options from which one can be chosen. IFUQ offers a simple way to check how the procedure will continue after the user makes a selection. A description of the individual IFUQ parameters is contained in the inline documentation of the IFUQ routine in the CFS.S.LMSLIB library.
*RUN (MVAR) ...
MVAR routines offer different options for the manipulation of CFS variables.
*RUN (MVAR)UPPER,&invar [,&outvar]
The function UPPER will convert all lowercase letters in the data of the &invar variable to uppercase. If a variable &outvar is specified, then the result will be returned to this variable, and the input variable remains unaltered. Otherwise, the &invar variable will be modified.
Example: *RUN (MVAR)UPPER,&IN,&OUT
&IN = '9abcDE.,-' --> &OUT = '9ABCDE.,-'
*RUN (MVAR)LOWER,&invar [,&outvar]
The function LOWER will convert all uppercase letters in the data of the &invar variable to lowercase. If a variable &outvar is specified, then the result will be returned to this variable, and &invar will remain unaltered. Otherwise, the &invar variable will be modified.
Example: *RUN (MVAR)LOWER,&IN,&OUT
&IN = '9ABCDE.,-' --> &OUT = '9abcde.,-'
*RUN (MVAR)GET-VALUE-ONLY,&invar [,&outvar]
The GET-VALUE-ONLY function deletes all blanks at the beginning and end of the &invar variable, as well as deleting leading nulls from the beginning. If an &outvar variable is specified, the result is stored in it, and the contents of &invar remain unaltered; otherwise the the result will be written to &invar.
Example: *RUN (MVAR)GET-VALUE-ONLY,&IN,&OUT
&IN = ' 0012 ' --> &OUT = '12'
*RUN (MVAR)DEL-LEADING-BLANKS,&var1 [,&var2] ...
The DEL-LEADING-BLANKS function deletes all leading blanks from the specified variable.
Example: *RUN (MVAR)DEL-LEADING-BLANKS,&VAR1,&VAR2
&VAR1 = ' 0012 ' --> '0012 '
&VAR2 = ' ABC' --> 'ABC'
*RUN (MVAR)DEL-TRAILING-BLANKS,&var1 [,&var2] ...
The DEL-TRAILING-BLANKS function deletes all trailing blanks from the specified variable.
Example: *RUN (MVAR)DEL-TRAILING-BLANKS,&VAR1
&VAR1 = ' 0012 ' --> ' 0012'
*RUN (MVAR)DEL-LEADING-ZEROES,&var1 [,&var2] ...
The DEL-LEADING-ZEROES function deletes all leading zeroes from the specified variable.
Example: *RUN (MVAR)DEL-LEADING-ZEROES,&VAR1,&VAR2
&VAR1 = '0012' --> '12'
&VAR2 = ' 0012' --> ' 0012'
*RUN (MVAR)HEX-TO-CHAR1 [,len] ,&invar [,&outvar]
The HEX-TO-CHAR1 function converts the hexadecimal contents of the specified variable (e.g. non-printable characters) bytewise to character form. The length of the input variable &invar must be 1 <= len <= 4. The length of the input variable should be specified if it contains binary nulls (X'00') at the end of the variable. If an output variable &outvar is specified, the result of the conversion is stored in it; otherwise the result will be returned to the &invar variable.
Example: *RUN (MVAR)HEX-TO-CHAR1,4,&VAR
&VAR = X'003FC100' --> '003FC100'
*RUN (MVAR)HEX-TO-CHAR2,&invar [,&outvar]
The HEX-TO-CHAR2 function converts the printable contents of the &invar input variable into decimal values. If an output variable &outvar is specified, the result of the conversion is stored in it; otherwise the result will be returned to the &invar variable.
Example: *RUN (MVAR)HEX-TO-CHAR2,&VAR
&VAR = '003FC100' --> '4178176'
*RUN (MVAR)HEX-TO-CHAR3 [,len] ,&invar [,&outvar]
The HEX-TO-CHAR3 function is a combination of the HEX-TO-CHAR1 and the HEX-TO-CHAR2 functions:
Example: *RUN (MVAR)HEX-TO-CHAR3,4,&VAR
&VAR = X'003FC100' --> '4178176'
*RUN (MVAR)CHAR-TO-HEX1 [,len] ,&invar [,&outvar]
The CHAR-TO-HEX1 function converts the printable contents of a variable byte for byte into its respective hexadecimal value.
1 <= len <= 4: length of the hexadecimal output string. The length of the output should be specified if leading zeroes (X'00') are to be inserted. The result will be returned to the &outvar variable if it was specified; otherwise the result will be returned to the &invar variable.
Example: *RUN (MVAR)CHAR-TO-HEX1,3,&VAR
&VAR = '12C1' --> X'0012C1'
*RUN (MVAR)CHAR-TO-HEX2,&invar [,&outvar]
The CHAR-TO-HEX2 function converts the decimal values in the &invar input variable to their respective hexadecimal values. The result will be returned to the &outvar variable if it was specified; otherwise the result will be returned to the &invar variable.
Example: *RUN (MVAR)CHAR-TO-HEX2,&VAR1,&VAR2
&VAR1 = '4801' --> &VAR2 = '12C1'
*RUN (MVAR)CHAR-TO-HEX3 [,len] ,&invar [,&outvar]
The CHAR-TO-HEX3 function is a combination of the CHAR-TO-HEX1 and CHAR-TO-HEX2 functions.
Example: *RUN (MVAR)CHAR-TO-HEX3,4,&VAR
&VAR = X'4801' --> X'000012C1'
*RUN (MVAR)FILL-STRING,len, &invar [,&outvar]
The FILL-STRING function pads the contents of the variable to the right with blanks (' ') up to length len. 2 <= len <= 80. The result will be returned to the &outvar variable if it was specified; otherwise the result will be returned to the &invar variable.
Example: *RUN (MVAR)FILL-STRING,10,&VAR
&VAR = ' 0012' --> ' 0012 '
*RUN (MVAR)FILL-STRING-RIGHT,len, &invar [,&outvar]
The FILL-STRING-RIGHT function shifts the contents of the variable len bytes to the right, and inserts blanks to the left. 2 <= len <= 80. The result will be returned to the &outvar variable if it was specified; otherwise the result will be returned to the &invar variable.
Example: *RUN (MVAR)FILL-STRING,6,&VAR1,&VAR2
&VAR1 = '0012' --> &VAR2 = ' 0012'
*RUN (MVAR)ADD-ARRAY, &invar1, &invar2, &outvar
The ADD-ARRAY function will perform a column-wise addition of all fields of two identically-structured variables. The fields to be added can also be in the form 999.99 or 999,99. Processing the fields proceeds from right to left, so therefore all columns in the two input variables must be correctly aligned from the right. The result will be written to the variable &outvar.
Example: *RUN (MVAR)ADD-ARRAY,&VAR1,&VAR2,&SUMME
&VAR1 = ' 12 1,35 99'
&VAR2 = ' 2 12,65 01'
&SUMME= ' 14 14,00 100'
*RUN (MVAR)SUB-ARRAY, &invar1, &invar2, &outvar
The SUB-ARRAY function will perform a column-wise subtraction of all fields of two identically-structured variables (&invar1 - &invar2). The fields to be subtracted can also contain numbers in the form 999.99 or 999,99. Processing the fields proceeds from right to left, so therefore all columns in the two input variables must be correctly aligned from the right. The result will be written to the variable &outvar.
Example: *RUN (MVAR)SUB-ARRAY,&VAR1,&VAR2,&DIFF
&VAR1 = ' 12 12,35 99'
&VAR2 = ' 2 1,65 01'
&DIFF = ' 10 10,70 98'
*RUN (MVAR)TIME-DIFF, &invar1, &invar2, &outvar
The TIME-DIFF function will subtract the time contained in &invar1 (HH:MM:SS) from that time contained in &invar2. The result will be written as HH:MM:SS in the &outvar variable.
Example: *RUN (MVAR)TIME-DIFF,&VAR1,&VAR2,&DIFF
&VAR1 = '11:54:22'
&VAR2 = '12:25:21'
&DIFF = '00:30:59'
*RUN (MVAR)TIME-DIFF-TEXT, &invar1, &invar2, &outvar
The TIME-DIFF-TEXT function will subtract the the time contained in &invar1 (HH:MM:SS) from that contained in &invar2. The result will be written in text form to the variable &outvar.
Example: *RUN (MVAR)TIME-DIFF-TEXT,&VAR1,&VAR2,&DIFF
&VAR1 = '11:54:22'
&VAR2 = '12:25:21'
&DIFF = '30 minutes, 59 seconds'
*RUN (SETLEN)&var1 [,&var2] ...
The SETLEN routine shortens procedure variables &var1, &var2 etc. such that, from the right, all blanks are replaced with X'00' .
Application: When using RDMASK, the procedure variables read in via FHS masks are padded with blanks to the length of the mask field. These variables can be shortened with SETLEN.
*RUN (RDJOBPAR) [col [,len], ] &var
The RDJOBPAR routine returns the job parameters (/LOGON ...,JOB-PAR='...') specified in the LOGON or ENTER command to the &var variable. The job parameter text for each task can be assigned to a string with a length of 1 to 128 bytes. This string can be used by *RUN (RDJOBPAR) to control CFS procedures in Dialog and Enter tasks. The options col and len can be specified to read from a particular column (1 <= col < 128) and to a specified length (1 <= len <= 80).
*RUN (SVAR)srch,&var,&rcvar [,&findvar1 [,&findvar2 ] ]
The SVAR routine checks the contents of the procedure variable &var for a search item srch specified in the general CFS search syntax (see page 8-/.
A return code will be passed to the second procedure variable, &rcvar, containing information about the result of the search operation.
'Y'|'N' The search item was found/not found.
'' Syntax error in the search argument.
If the search was successful (&rcvar='Y'), the portion of the &var variable following the search string will be returned to the optional variable &findvar1.
If the search was successful (&rcvar='Y'), the portion of the &var variable in front of the search string will be returned to the optional variable &findvar2. &findvar2 can only be specified in conjunction with &findvar1.
The source code for the SVAR routine is contained in the CFS.S.LMSLIB PLAM library, and can be freely modified by the user.
*RUN (URLOUT)HTTP [,type]
The URLOUT routine is used in conjunction with our URLSERVER product.
An HTTP header with the specified content type will be sent to the internet browser linked to the URLSERVER.
The sent HTTP header contains the following data:
HTTP/1.0 200 OK
Content-Type: type
(empty lines)
type The content type can be specified as CFS Variable &var or as a string.
If the type parameter is omitted, the content type will default to "text/html".
Examples: *&TYPE='text/html'
*RUN (URLOUT)HTTP,&TYPE
*RUN (URLOUT)HTTP,text/plain
*RUN (URLOUT)HTTP,'text/plain'
*RUN (URLOUT)HREF ,url
A HTTP header with the status code 302 (request another URL address) will be sent to the internet browser.
This statement is only relevant when it is sent as the only URLOUT statement at the end of a CFS procedure, i.e. a file is first created, then that file is displayed with a *RUN (URLOUT)HREF statement. All functions of the URL Server can then be utilised, e.g. VIEW, XVIEW, EDTW, PDF.
url The URL address can be specified as a CFS variable &var or as a string.
Examples: *&GOTO='../PDF/TEST.LST'
*RUN (URLOUT)HREF,&GOTO
*RUN (URLOUT)HREF,../PDF/TEST.LST
*RUN (URLOUT)DATA [,string] [ ,&var1, &var2, ... ]
The specified string and/or the contents of the CFS variable will be sent to the internet browser. The data will be converted from EBCDIC to ISO8859.
string Text with data and HTML tags to be be sent to the internet browser. The string can be enclosed in quotes.
&var1 ,&var2 ...
The specified variables can contain text and HTML tags, and will be sent to the browser sequentially, and directly following any specified string. Each variable can contain up to 80 bytes of text, with the total length of all variables not exceeding 4096 bytes.
Examples: *&VAR1='Data Line 1<BR>'
*&VAR2='Data Line 2<BR>'
*RUN (URLOUT)DATA,'<BR>',&VAR1,&VAR2
*RUN (URLOUT)DATA,'FSTAT for File: '
*RUN (URLOUT)DATA,&FILE
*RUN (URLOUT)DATA,<BR>
*RUN (URLOUT)DATAFILE ,file
The contents of the specified file will be sent to the internet browser. The data will be converted from EBCDIC to ISO8859.
The file must contain data in HTML format, or else the HTML tag <PRE> must be issued before the *RUN (URLOUT)DATAFILE statement, or else the content type "text/plain" must be used.
file Name of the file whose content should be output. The name of the file can also be specified by means of a CFS variable.
Example: *RUN (URLOUT)DATAFILE,TESTHTML
*RUN (SYSOUT) [EXTEND] ,&sysout, &oldsysout
This function enables the SYSFILE SYSOUT file in a procedure to be redirected to a new file, and the name of the old SYSOUT file to be saved to a CFS vaiable. This enables the previous SYSOUT file to be re-assigned following the creation of SYSOUT data.
EXTEND The newly-created SYSOUT file will be created with OPEN-MODE=*EXTEND.
&sysout CFS variable containing the name of the new SYSOUT file.
&oldsysout CFS variable which is to contain the name of the old SYSOUT file.
Example: *&SYSOUT='#OUT'
*RUN (SYSOUT),&SYSOUT,&OLDSYSOUT
*/SHOW-FILE-ATTR &FILE,INF=*A
*RUN (SYSOUT)EXTEND,&OLDSYSOUT,&SYSOUT
*RUN (URLOUT)DATAFILE,&SYSOUT
*RUN (WRITECON)&var
The WRITECON routine displays the contents of &var on the console (TYPE).
Program linkage for Run modules:
When calling the user module, the general purpose register R1 will display a parameter list in the following way::
DC A(param) Control parameter (see above), or blank, if param has not been specified at the time the module was called.
DC A(varlist) varlist: DC A(var1)
DC A(var2)
.....
DC A(var-x)
DC A(0) End flag
A CFS procedure variable var-x is structured as follows:
DC CL20'var-name' Procedure variable name
DC XL80'00' Procedure variable value (initialised with X'00')
The value of the procedure variable will be taken from the beginning till the first X'00'. A procedure variable that has not yet been initialised (XL80'00') will contain an empty string, ''.
Communication from CFS procedure --> user module --> CFS procedure is possible using procedure variables.
When returning from the user module to CFS, the contents of general purpose register R15 will not be evaluated.
Display Next Mask/WRTRD Output
*SCRUPD Screen Update. WRTRD messages requesting the next input are suppressed when running CFS procedures. For example, the CFS masks in which the user provides input in dialog are not displayed. The *SCRUPD statement allows the mask for the next WRTRD message to be displayed. *SCRUPD causes the message (mask) that requests the next input to be displayed on the screen with WROUT.
*SCRUPD may not occur before a *002 statement.
The *SCRUPD statement can be used, for example, when the commands in a CFS procedure may be amended by the user before the commands are executed (see the *STEP statement below). By displaying the mask, the user will be informed on which file or library element the suggested command will act.
*SEND 'text' The text enclosed in quotes will be sent to a $CONSOLE Connection opened under CFS on the local host system. The text may also contain CFS procedure variables. Example: *SEND '&TSN..N'
For an example of the *SEND statement, see page 19-.
*SENDn 'text' The text enclosed in quotes will be sent to the CFS Connection designated by n. Applications to which the text can be sent include $CONSOLE on any host, as well as $VMCONS.
Redefine Procedure-specific Control Character
*SET [TAB=x] [, NOC=y] [, PAR=p] [, EM=Y|N] [, CASE=Y|N|X]
Redefine the control characters that have a special function in the CFS procedure language.
TAB Tabulator character (Default: C'~')
NOC 'Don't Care' character character (Default: C'|').
PAR Parameter character for CFS procedure variables (Default: C'&').
A full description of CFS procedure variables can be found in the "Procedure Variables" section on page 19-.
EM Processing CFS Commands.
EM=Y In procedure mode, command input is terminated with the End marker.
EM=N In procedure mode, command input is terminated with ENTER, i.e. transmitted without the End marker, as in Dialog mode.
CASE Processing Lowercase Characters in the *IF &var=..Statement.
CASE=Y Lowercase characters will be recognised when comparing two variables, or a variable with a constant.
CASE=N Lowercase characters will not be recognised when comparing two variables, or a variable with a constant; i.e. they will be converted into uppercase before the comparison.
Control Characters in CFS Procedures
By default, the C'~' character specifies a tabulator character for procedure-simulated mask entry (file list/Display mask). The tab character will result in the following character(s) being entered in the first Action Code field (column 72), or in the next Action Code field/Modify area.
C'|' serves as an 'Don't Care' character (Not Overwrite Character) for the simulated input in CFS masks (file list/Display mask) during a CFS procedure. The 'Don't Care' character will result in the character from that position being used from the mask as input.
Note:
When creating CFS procedures, it is recommended that the user assigns values at the beginning for the tabulator and 'Don't Care' characters:
If the '%' and '#' characters do not appear in the procedure data, they can be set to the tab and 'Don't Care' character respectively by the statement *SET TAB=%,NOC=#.
Examples:
The following examples assume the statement *SET TAB=%,NOC=# has been issued.
%M
The Action Code "M" is inserted for the first data object in the list.
%%A##BBB
Assumption: The Modify mode of CFS is active. The first position of the data area is overwritten with an 'A' ('%%' skips both the command and Action Code fields). Columns 2 and 3 of the Modify area are not amended (the existing values are taken instead). Columns 4 to 6 will be overwritten with 'B'. An end marker will automatically be generated at the end of the input record, so that the rest of the mask is not overwritten.
*SETSW { ON | OFF } = (n1, ...)
Set or reset task switches. The syntax is identical to that in the BS2000 /SETSW command. Only SETSW ON or SETSW OFF may be specified for one or more switches.
*SKIP .label Unconditional jump to the specified label. A branch towards the front of the procedure (backward jump) is also possible. If the specified label is not found, the procedure will be terminated. A procedure variable containing the branch label as text (*SKIP &var) can be specified instead of .label. For an example, see page 19-.
*STEP text The specified text will be displayed, and can be amended by the user. This text, amended or not, is then used as the input for the procedure.
If the recommended text is answered with the K1 key, the command will not be executed, and the procedure will be terminated.
Halt the Procedure until Acknowledgement by the User
*STOP ['text'] The text enclosed in quotes will be displayed. The user must acknowledge the message with DUE1 before the procedure will be continued. The text can be up to 2040 bytes, and can also contain control codes (output in Line mode). If no text is specified, the default message "PLEASE ACKNOWLEDGE" will be displayed.
Display/Save Contents of of Procedure Variables
&var The contents of the procedure variable will be displayed on screen, or saved to a file. If &var is not specified, the names and contents of all procedure variables will be displayed, or saved to a file (see below).
file A specified variable, or all variables defined in the procedure (*&var= ...), together with their current contents, will be saved to a file with the specified name. They can then be loaded later into another procedure with the *LV statement.
If file is not specified, the names and contents of all variables will be displayed on the screen. If &var is not specified, the comma in front of the file name can be omitted.
E The file is opened in Extend mode.
The records saved in the SV file have the following format:
20 byte variable name; 1 to 80 byte variable content. The contents of the variable can (but does not have to be) padded with nulls (X'00') up to 80 bytes.
Suspend Procedure Execution for a Specified Time
n The procedure will be suspended for n seconds. If n is not specified, the wait will be indefinite.
.label After the waiting period has elapsed, the procedure will continue execution by branching to the specified label (*SKIP .label).
The waiting period specified in the *WAIT statement can be interrupted at any time by the user pressing the K2 key. In this case, the procedure will not branch to a specified (.label) branch point.
Display a Message on the Screen
*WRITE ['text'|CLEAR] [, file [,O|E|N] ]
The text enclosed in single quotes will be displayed on screen, or written to the specified file.
text The text may contain constants, CFS procedure variables or logical control codes (WROUT output in Line mode). If text is not specified, CFS will display an empty line.
CLEAR The contents of the screen are cleared.
file Name of the file into which the text should be written (Fcbtype=SAM).
O The file will be opened in Output mode. An existing file with the same name will be overwritten. The file will be closed after the record has been written.
E The file will be opened in Extend mode. The record will be appended to the end of the existing file, and the file will be closed after the record has been written.
N The file will be opened in Extend mode, and will remain open after the record has been written. This option will prevent each write operation from extending the file by a full PAM page.
Display a Message in the System Line
*WRITESYS 'text' The text enclosed in quotes will be displayed in the system line of the terminal.
The statement *WRITESYS '' will restore the original contents of the system line ("LTG").
DO [N,] [ file | element | lib(element) | %name | %?] [, param, ...]
The procedure specified contains a PROC statement with any relevant parameters. Normally, the parameter mask will be displayed, in which all parameter values may be entered.
N Specifying DO N,... will suppress the parameter mask. The procedure parameters will be used as specified in the DO command (see below), or as they have been predefined in the PROC statement.
file The CFS procedure is stored in the specified file.
element The procedure is stored as the specified element in CFS.USERLIB or in the secondary userlib (see notes below). If the element is stored in a PLAM library, it must be a type S (Source) element.
lib(element) The procedure is stored as an element in the specified library.
%name A parameter set saved previously with the command SP %name under the abbreviation %name is to be used. A parameter set is a named procedure, together with a particular set of parameters. For a full description of the SP command and the use of %name, see page 11-.
%? All relevant parameter sets will be displayed in a list, from which one may be selected by marking it.
param Optional specification of CFS procedure variables. As for BS2000 DO procedures, both positional and keyword parameters can be given. The *PROC statement defines the type of parameter. Parameters cannot be specified in conjunction with a %name parameter set.
Positional parameter: Only the value of the required parameter should be specified. The correct sequence of positional parameters must be observed. If, for example, only the second parameter needs to be given, then an additional comma must be inserted as follows: DO procedure,,value.
Keyword parameter: The parameter name, followed by an '=' character, and then the parameter value must be entered. The parameter name and the default value can be defined in the *PROC statement.
Notes:
CFS will process a DO command in the following way:
If lib(element) or %name is specified, the CFS procedure to be executed is defined uniquely. In all other cases, the procedure is sought according to the following hierarchy:
a) CFS will search for an element with the specified name in the assigned userlib (Standard: CFS.USERLIB).
b) CFS will search for an element with the specified name in the secondary userlib. The secondary userlib can either be assigned with a /FILE ...,LINK=USERLIB command, or the default library, $userid.CFS.USERLIB.STD will be used. $userid is the userid under which the CFS program phase is stored.
c) A file is sought with the specified name.
When neither a), b) nor c) produce a result, an error message will be displayed. To change the standard CFS userlib, see the UL command on page 18-.
If the DO command is specified without any parameters, the last procedure to have been executed will be called again.
If a parameter value contains blanks or special characters, then the value must be enclosed in quotes.
If the value contains quotes, these must be entered twice.
If the procedure does not contain a *PROC statement, no mask-controlled parameter prompting is possible. It can also not be specified via a %name option.
If positional parameters are specified when calling a procedure that contains no *PROC statement, then these may be accessed from within the procedure only via the names &1 (first positional parameter), &2 (second positional parameter), and so on.
If a user encounters problems when running a procedure, there are two possibilities for testing them.
a) All statements in the procedure can be logged during execution by inserting a *PROC A statement in the first line of the procedure. PROC A will display all the CFS procedure statements, as well as all data records passed to CFS. If a variable is used in a statement or data record, then that statement or record will be displayed both before and after the variable substitution.
b) Switch on the hardcopy mode with an HC file,O command. file is the name of the hardcopy file to be used. A hardcopy file can be used by the procedure author to check the sequence and syntax of the commands passed to CFS.
If the SYSDTA input record is shorter than the expected mask entry, CFS will behave as though the input was terminated with < (End marker).
When entering commands via SYSDTA, the output portions of the mask will be displayed with WROUT. These can be suppressed by /SETSW ON=4 (reduced output volume).
Returning to the main CFS task after opening Connections:
The K2 key cannot be generated in the CFS procedure-controlled mode. The escape symbol, ^ , can be used to switch from a Connection to the CFS main task, without using the K2 key.
Example:
OC1/LOGON userid1,acct1,C'passw1'
^
OC2/LOGON userid2,acct2,C'passw2'
^
If a &(jv-name) clause appears in a procedure-controlled input, then the CFS input processor will substitute the current value of the Job variable at this position. It is thus possible to automate Connection processing to $DIALOG, where the current LOGON password is stored in a Job variable.
Example:
OC1/LOGON userid1,acct1,&($TSOS.DAILYPASSW)'
^
In this example, the $TSOS.DAILYPASSW Job variable contains as value a string C'....' or X'....'.
BS2000 commands that are entered from a Connection in procedure-controlled mode should be entered without the leading oblique (/).
Example:
OC1/LOGON userid,acct-nr,C'passw'
EXEC program
BS2000 commands must be preceded by a blank. If not, the End of File condition will be activated for SYSDTA.
The following procedure (stored in CFS.USERLIB , element L) allows the user to mark any of the displayed files/library elements with the Action Code X. After entering the command A (process Action), the marked files will be formatted and printed with the help of an ONXLIST Variable Action. The CFS procedure is called by entering DO L, or DO L,file. In the last case, the first positional parameter, file, will be assigned to the procedure variable &1.
*IF &1 = '' &1 = '#LIST.FRANK'
*SET TAB=%
ONXLIST &1
*WRITESYS 'Mark the files to be printed'
*ON %TERM CONTINUE
*DIA
U
NPFSTAT &1
%PD7S
* Print the created list on remote printer 7 with Space=E (PD7S)
U
* Display the selected list again.
RL
The following procedure tests if a Connection has already been opened under CFS to the UTM application TEST. If so, it switches to this Connection. If not, the procedure determines the next free Connection number, establishes the connection to TEST, and issues a KDCSIGN command.
*&N=0
.LOOP
*&XX='CON'&N
*IF &&XX = 'TEST' SKIP .CC
*&N=&N+1
*IF &N<10 SKIP .LOOP
*IF &NEXTCON = '' SKIP .NOFREECONN
OC&NEXTCON TEST,CFS1
KDCSIGN ......
*SKIP .END
*
.NOFREECONN
*WRITESYS 'All Connections occupied. TEST application cannot be opened'
*SKIP .END
*
.CC
CC&N
*
.END
The following BS2000 DO procedure searches all J-type elements (Job Control) in a PLAM library for the occurrence of the string '12132716' (LOGON password of a particular userid). The resulting records will be written to a SAM file. Next, the records are processed with EDT such that all instances of '12132716' are replaced by '884310'. The original library elements are updated with these new records with a CFS REWRITE command.
/PROC C,(&LIB=LMS.PROC,&PSWOLD='12132716',&PSWNEW='884310'),SUBDTA=&
/SYSFILE SYSDTA=(SYSCMD)
/SETSW ON=(1,4)
/EXEC CFS
*002 FILE=LMS &LIB;FCB=J;VAR=ON&FIND'&PSWOLD'=W #RESULT
AU
NQR
EDT,#RESULT
ON&:2-2:FIND'*'COPY TO (1) KEEP
ON&CA'&PSWOLD'T'&PSWNEW'
COPY &(1)
WRITE O
HALT
REWR #RESULT
END
/SETSW OFF=(1,4)
/ENDP
The DO procedure described below creates a console that performs the following functions:
1) System dumps will be automatically answered with tsn.Y.
2) Those users logged on as TSOS or TT08 are allowed to enter any console command via a /TYPE CFSCON:/cmd or /TYPE CFSCON:tsn.xxxx command.
3) The DO procedure will be terminated by entering a /TYPE TERMINATE CONSOLE command.
/PROC N
/SYSFILE SYSDTA=(SYSCMD)
/SETSW ON=(1,4)
/EXEC $CFS.CFS
*002 FILE=NO
OC9$CONSOLE,,,R
xxxxx,C'sssss'
*ON %OUT=($CFS.CFS.PROCLIB(X/SRCITEM)) RESUME
CC9/STA MSG check if any messages are outstanding
*SKIP .SETTSN
.LOOP
*ON %OUT activate last *ON %OUT condition
CC9
.SETTSN
*&TEXT=%PTR(1,80) mark message text
*WRITE '&TEXT' display message text
*&TASK=%PTR(1,4)
*SKIP &SLABEL
.SYSDUMP
*WRITE '--------> &TASK..Y'
*SEND '&TASK..Y'
*SKIP .LOOP
.CFSCONSOLE
*IF %OUT=:1:'%' &TASK=%PTR(1,4)
*&VAR='USER-ID('&TASK.')'
*IF &&VAR='TSOS' SKIP .ALLOW-CONSINPUT
*IF &&VAR='TT08' SKIP .ALLOW-CONSINPUT
*WRITE '/MESS TSN=&TASK,USER-ID &&VAR. CONSOLE INPUT NOT ALLOWED'
*SEND '/MESS TSN=&TASK,USER-ID &&VAR. CONSOLE INPUT NOT ALLOWED'
*SKIP .LOOP
.ALLOW-CONSINPUT
*&TEXT2=&TEXT(1,50)
*WRITE 'COMMAND EXECUTED: &TEXT2'
*SEND '&TEXT'
*SEND '/MESS TSN=&TASK,COMMAND EXECUTED: &TEXT2'
*SKIP .LOOP
.EXIT
*ON %TIME=0 RETURN Return to the CFS command field
DC9
END Terminate CFS
/SETSW OFF=(1,4)
/ENDP
The conditions determining which console messages should act as a catalyst are stored in the element X/SRC ITEM in the $CFS.CFS.PROCLIB PLAM library. In this example, the element will have the following contents:
'SYSTEMDUMP DESIRED'+:1-20:'?' .SYSDUMP
'CFSCON:' .CFSCONSOLE
'TERMINATE CFSCONSOLE' .EXIT