*RUN Call User Subprogram

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.