Here are functions for handling other than JCL Procman objects.

INSMANACT

Inserts a manual activity (i.e. a text displayed to Procman user). Optionally the activity name where the text is displayed can be specified.

Inserts a manual activity (i.e. a text displayed to Procman user). Optionally the activity name where the text is displayed can be specified. Use this ver-sion if you want to insert more activities.

WRITEINDB

Writes a note in DD HOSXOUT (WTEMPS section)

The data created by this function become available in HOSXIN of the activity specified as 3rd parameter (TARGET). You can:

• specify just an activity name, for example: JCL_NEW_APPROVE

• or append also a system id to the activity name, for example: JCL_NEW_APPROVE.SYSH_ID1

When the system is present (it must be separated from the activity name with a dot) then the data will be available in HOSXIN of the selected activity only on the specified system. This allows you to specify different HOSXIN content for different target systems of the same activity.

CACHEINFO

Definition

Prints information about cached table records to SYSPRINT.

Example

/* print cached table records */
CALL SAY(CACHEINFO());

INSMSG

Definition

Inserts a message. When the message text contains variables, their values must be passed to the PARM list.

Example

The function uses the messages that are defined under JCK-MSG. Each message has a CODE, a SEVERITY and a MESSAGE that can contain variables.

TST0001W 04 THE JOB FINISHED WITH &VAR1 WARNINGS IN ENVIRONMENT &VAR2
TST0002E 08 THE JOB FINISHED WITH &VAR1 ERRORS IN ENVIRONMENT &VAR2

/* insert a warning message */
CALL INSMSG("TST0001W", [7, "TEST"]);

/* insert an error message */
CALL INSMSG("TST0002E", [3, "TEST"]);

INSMSGEX

Definition

Inserts a message with an explicit severity. When the message text contains variables, their values must be passed to the PARM list.

Example

For this example, the same messages are being used as in INSMSG.

/* insert a warning message with explicit severity */
CALL INSMSGEX("TST0001W", 4, [7, "TEST"]);

SAY

Definition

Prints a value to SYSPRINT. Optionally, a prefix can be defined that is appended in front of the value.

Example

Using a prefix can be useful, if a variable is being used that changes depending on the context (e.g. a different system). This could also be achieved via concatenation.

/* print a message */
CALL SAY("TEST");

/* print a concatenated message */
CALL SAY("PRE"!!"TEST");

/* print a message with prefix */
CALL SAY("PRE", "TEST");

These functions can be used to get and set values of forms.

ADDFORMOPTION

This function allows to insert options that are visible in select field on FRM form.

Example:

call addformoption('FRM_JCK_DD_DSNW','DD_DSNW_LRECL','80', '80');
call addformoption('FRM_JCK_DD_DSNW','DD_DSNW_LRECL','133', '133');
call addformoption('FRM_JCK_DD_DSNW','DD_DSNW_LRECL','255', '255');

This example inserts 3 options to the select box of DD_DSNW_LRECL field in FRM_JCK_DD_DSNW form. Labels displayed in the form are equal to values, which are used.

The function never removes options that already exist. It only appends new ones.

ATTR

Returns a value of the requested attribute of the focused form field. Returns an empty string and issues a warning if no form field is focused.

Returns a value of the requested attribute of FIELD field of the form assigned to the current JCL statement. Returns an empty string and prints a warning if the current statement has not assigned a form or the field does not exist.

Returns a value of the requested attribute of IDX generation of FIELD multiple form field of the form assigned to the current JCL statement. Returns an empty string and prints a warning if the current statement has not assigned a form or the field does not exist.

If you have multiple form fields (i.e. expand='Y' is set in the XML definition) then you can get an attribute of a selected generation by specifying the index. Use 1 for the first one, 2 for second one, ... It is also possible to use the format with just 2 parameters if you set the field name in 'FIELD.IDX' format.

DELFORM

Deletes a form from the current JCL statement (if it exists). After calling this function the JCL statement has no more a form assigned.

FIELD

Returns a value of the requested form field. If the current statement has not assigned a form or if the field does not exist then it returns an empty string and prints a warning. If the field value is numeric then it returns NUM, other-wise it returns the value as STR.

Returns a value of the requested form field of IDX generation. This version of the function is aimed for multiple fields (fields inside of forms with EX-PAND='Y' group's option in XML definition). If the current statement has not assigned a form or if the field does not exist then it returns an empty string and prints a warning. If the field value is numeric then it returns NUM, other-wise it returns the value as STR.

In spite of the fact the 2nd version of the function is intended for multiple fields and it is recommended in this case, you can also get values of multiple fields by the first version. You just need to specify the name in format: "FIELDNAME.IDX".

FIELD CHANGED

Returns true if the field (the current one if NAME is not specified, otherwise NAME) exists in jcl_old XML section but its value differs from the current one. In all other cases returns false.

FIELDISNEW

Returns true if the field (the current one if NAME is not specified, otherwise NAME) doesn't exist in jcl_old XML section. This can be because in the past no form was assigned to the JCL statement or the form did not contain this field.

FIELDS

The field name that is tested. When not specified then the focused field is used. When no field is focused or when the field does not exist then it prints a warning and returns false.

This function returns an associative list, there keys equal to field names and values equal to field val-ues. In case of multiple fields the values are stored in a nested list, where its keys contain indexes and values contain field values. You can iterate values obtained by this function as shown in the example. Calling TYPE function is important here, as to access multiple fields in a nested list is possible only when the field value is stored as a list.

Example :

do(nextjclstmt());
  if (hasform());
    foreach(fields() as &NME => &VAL);
      if(type(&VAL) EQ 'LIST');
        call say('Multiple items of: '!!&NME);
        foreach(&VAL as &IDX => &V);
          call say('IDX:'!!&IDX!!',VAL:'!!&V);
        foreach(end);          
      else;
        call say('NME:'!!&NME!!',VAL:'!!&VAL);
      if(end);  
    foreach(end);
  if(end)	
do(end)

This example prints values of a form fields (it the JCL statement has a form assigned) to SYSPRINT.

In case of a multiple field its values are stored in a nested list, which is iterated when TYPE function returns 'LIST'. In case of a single field TYPE returns 'STR' and its value is stored simply as a string.

FORM

Returns a name of the form that is assigned to the current JCL statement. Returns an empty string if the statement has no form.

FORMCHANGED

Returns true if at least one field in the form has a different value than in jcl_old data of the form of the current JCL statement. Returns true also if there is no form in the old data and now it is or vice versa.

FORMISNEW

Returns true if the current JCL statement has a form assigned but in the past it didn't. That means that there is no form assigned to the current statement in jcl_old XML section or that this section doesn't exist at all.

HASFORM

Returns TRUE if the current JCL statement has a form assigned. Otherwise it returns FALSE.

HOCHANGEFORM

Returns true if the old and new forms are different. The old value is read from HOS_FORM_ORIG HOSXIN parameter, while the current one from HOS_FORM_CURR.

SETATTR

Sets a new value of the selected attribute of the focused form field. If no form field is focused then it does nothing but issues a warning.

Sets a new value of the selected attribute of the specified form field. If current statement has not assigned a form or if the field does not exist then it does nothing but issues a warning.

Sets a new value of the selected attribute of the specified multiple form field. If current statement has not assigned a form or if the field does not exist then it does nothing but issues a warning.

If you have multiple form fields (i.e. expand='Y' is set in the XML definition) then you can set an attribute of a selected generation by specifying the index. Use 1 for the first one, 2 for second one, ... It is also possible to use the format with just 3 parameters if you set the field name in 'FIELD.IDX' format.

You can use the following field attributes:

• state, state of the form field, for example: OK (green field), modify (yellow field)

• must, Y if the field is mandatory, N otherwise

• expr, integer or regular expression

• help, help text displayed in the form

• range, range of valid integer values. For example [1-80] accepts any number from 1 to 80 in the field

• disabled, Y if the form field should be disabled, N otherwise

• label, overwrites the form field's label

If the attribute name equals 'expr' then the value must be one of the following:

• valid regular expression

• integer with a meaning of field length. PRX converts it to this regular expression: /^[^[:space:]]{xxx}$/ where xxx is your number.

SETFIELD

Sets a new value of the specified form field. Prints a warning if the field or form doesn't exist.

When the value is surrounded by apostrophes then the apostrophes are automatically removed. If you dislike this feature then you can deactivate it by #SET_FIELD_REMOVE_APOS contant.

SETFORM

Sets a form to the current JCL statement. If the current JCL statement al-ready has a form assigned then it is replaced with the new one. If the new form name equals the old one then it does nothing.

USEOLDJCL

Performs matching of form data of old JCL to the new JCL. Returns a number of successfully matched JCL statements.

NOW

Definition

Returns the current date/time in the requested format.

Keywords

Example

/* default -> 2024-07-15 15:24:33 */
SET &A = NOW();

/* short -> 24-7-15 15:24:33 */
SET &B = NOW("ZY-ZM-ZD HH:II:SS");

/* extended -> 2024-07-15 15:24:33.849030 */
SET &C = NOW("YYYY-MM-DD HH:II:SS.999999");

/* outspoken -> 2024, JUL 15, 15:24:33 */
SET &D = NOW("YYYY, MMM DD, HH:II:SS");

/* days into the year -> 2024, DAY 197, 15:24:33 */
SET &E = NOW("YYYY, DAY DDD, HH:II:SS");

/* other formats -> 07/15/2024 */
SET &F = NOW("MM/DD/YYYY");

SLEEP

Definition

Pauses the program for the specified time in milliseconds.

Example

/* pause the program for 3 seconds */
CALL SLEEP(3000);

TIME

Definition

Returns the date and time of the most recent update. The initial update occurs when the program starts. Subsequent updates are performed using the UPDATETIME-function. This function is useful when consistent date and time values are needed across different parts of the program.

Example

/* default -> 2024-07-15 15:24:33 */
SET &A = TIME();

/* modified-> 24-7-15 15:24:33 */
SET &B = TIME("ZY-ZM-ZD HH:II:SS");

UPDATETIME

Definition

Updates the stored date and time to the current date and time. After performing the update the TIME-function will return the new values.

Example

/* old time -> 2024-07-15 15:24:33 */
SET &A = TIME();

/* update time -> 2024-07-15 17:26:12 */
CALL UPDATETIME();

/* new time -> 2024-07-15 17:26:12 */
SET &A = TIME();

ALLIN

Returns TRUE if all elements from SEARCH exist also in LST. Items in LST list can contain wildcards.

ANYIN

Returns TRUE if at least one element from SEARCH exists also in LST. Items in LST list can contain wildcards.

EXPLODE

Converts a string (VALUE) to a list by splitting it by the use of SEPAR sepa-rator. The separator is consumed by the function, which means the resulting list items do not contain it.

IMPLODE

Converts a list to string by joining list's element with SEPAR glue.

IN

Checks whether VAL value exists in LST list. This function always searches for values, never for keys. Items in the list can contain wildcards.

KEYIN

Checks whether KEY key exists in LST list. If keys are used in the list then it compares keys. If the list uses automatic (i.e. numeric) keys then the key must be numeric. Items in the list can contain wildcards.

KEYS

Returns a list of keys used in the list passed as a parameter. This is useful mainly when the parameter is an associative list. By calling this function the keys can be transformed to a standard list. If the list passed as a parameter is not associative then the function returns a list of numbers, because num-bers are used as keys in non associative lists.

KSORT

Returns an associative list sorted by keys. This function fails when used with simple (non associative) list.

MERGE

Returns a list that contains all elements of all lists passed as arguments. The function can be used both with standard lists (with automatic keys) or with associative lists. You can merge up to 5 lists by one function call. All lists that are merged must have the same type - they all must use automatic keys or be associative. A content of the lists passed as arguments is not affected by the function.

When the lists use automatic indexes then the result contains all elements of the source lists. The first element has index 1, the last one has index equal to their count. In case of associative lists the key val-ues are important. If there are elements in the merged lists having the same key values, then such an element appears just once in the result and its value equals to the last one used

Example 1:

SET &A = ['a', 'b', 'c'];
SET &B = ['d', 'e', 'f'];
SET &C = ['g', 'h', 'i'];
SET &X = MERGE(&A, &B, &C);

The value of X is: ['a','b','c','d','e','f','g','h','i']

Example 2:

SET &A = ['a' => 'one',   'b' => 'two'];
SET &B = ['a' => 'three', 'c' => 'four'];
SET &C = ['a' => 'five'];
SET &X = MERGE(&A, &B, &C);

The value of X is: ['a' => 'five', 'b' => 'two', 'c' => 'four']

PUT

Inserts a new value to the list. This function can be used only with lists hav-ing automatic indexes.

Inserts a new pair or key and value to the list. This function can be used only with lists that use keys. If the key already exists in the list then it is set the new value.

PUTALL

Inserts all items from the source list to the target one. The new items are appended at the end. This function can be used only with target lists having automatic indexes. Items in the source list can be of any type.

Example:

set &A=[1,2,3,4,5];
set &B=['x','y','z'];
call putall(&B, &A);

After calling putall the content of &A will be: [1,2,3,4,5,'x','y','z']

PUTALLAT

Inserts all items from the source list to the target one at the specified posi-tion. If the position if higher than the current number of elements of the target list then the new items are appended to its end. This function can be used only with target lists having automatic indexes. Items in the source list can be of any type.

Example:

set &A=[1,2,3,4,5];
set &B=['x','y','z'];
call putall(&B, 3, &A);

After calling putall the content of &A will be: [1,2,'x','y','z',3,4,5]

PUTAT

Inserts a new value to the list at POS position. Existing items at POS and higher positions are shifted.

REM

Removes VAL value from the list. It always compare values, even when the list uses keys.

REMAT

Removes a value from the list at specified position. If the list does not use keys then VAL must be a number and has a meaning of a position. Other-wise VAL has a meaning of key.

REVERSE

Returns a list that has items sorted in the reverse order. It can be used with normal as well as with associative lists.

SAME

Returns TRUE if all pairs of a key and a value from L1 appear also in L2 and there is no key-value pair which exists only in one of the two lists.

SAMEKEYS

Returns TRUE if all keys from L1 appear also in L2 and there is no key which exists only in one of the two lists.

SAMEVALUES

Returns TRUE if all values from L1 appear also in L2 and there is no value which exists only in one of the two lists.

SIZE

Returns a number of elements in LST list.

SORT

Returns a list with sorted original list items. If it is used with associative lists then the result is sorted by values. If you need to sort by keys, use KSORT function instead.

SUBLIST

Returns a sublist of LST list. The new list contains elements starting at POS position of the original list. POS can be negative, then it measures from the end.

Returns a sublist of LST list. The new list contain max LEN elements of the original list starting from POS position. POS can be negative, then it measures from the end.

SUBLIST function works only with lists with automatic numeric keys. It can't be used for lists with user-defined keys.

VALUES

Returns a list of values used in the list passed as a parameter. The returned list is not associative. That means indexes in the returned list are numbers.

BREAK

CONTINUE

READFILE

COUNT

FIND

LC

LEFT

LENGTH

LIB

LPAD

LTRIM

MEM

PART

QUAL

QUALCNT

REPEAT

REPLACE

REPLACEALL

REPLACELIB

REPLACEMEM

REPLACEQUAL

RFIND

RIGHT

RPAD

RTRIM

SUBSTR

TRANSLATE

TRIM

UC

WORD

WORDS

CATEXIST

CMTINJCL

EMPTY

EXIST

GDGENTRY

GDGLIMIT

ISDSN

ISNUM

MEMEXIST

RULEOK

SWITCH

TABLE

TABLECOUNT

TABLEREC

TYPE

VALID

WHEN

DELVAR

Definition

Deletes a variable with the specified NAME and frees up its memory.

Example

SETVAR

Definition

Assigns a VALUE to a variable of the specified NAME and creates that variable, if it didn't exist beforehand.

Example

XMLATTR

XMLDDCONCATPOS

XMLDDFIND

XMLDDNAME

XMLDDPOS

XMLFIND

XMLFINDCHILD

XMLCHILDREN

XMLMATCHTO

XMLNAME

XMLPARENT

XMLPOS

HOACTION

Returns a name of the current process action.

HOLOGONUSER

Returns a name of the user logged into Procman.

HONAME

Returns a name of the current process.

HOPREVIEW

Returns TRUE if the preview mode is on. The information is read from hos_preview HOSXIN option.

HOTYPE

Returns a type of the process. It uses is_change HOSXIN option. If it is set then it returns CHANGE, else it returns NEW.

OPT

Returns a value of an option from section in HOSXIN file.

READXML

Returns a value of XML attribute at the specified path.

Returns a value of XML attribute at the specified path. It returns a value of 'value' attribute.

Returns a value of XML attribute at the specified path. It returns a value of 'value' attribute. The default value returned when the section or attribute is not found is an empty string.

The path is a string containing space-separated tokens. Each token has a meaning of one XML section.

Each token can be followed with modifiers that specify further search criteria. These modifiers are:

• (AttrName='AttrValue') : AttrName is an attribute name and AttrValue is its value.

• (Position): a position of the section (matching AttrName='AttrValue' criteria if present) in its parent section.

Both modifiers are optional.

If more filters (AttrName='AttrValue') are required then they must be comma separated (AttrName1='AttrValue1',AttrName2='AttrValue2',...)

Example 1:

SET &X=READXML("hos jcl_old job exec parms parm(name='cond')");             

This example returns a value of 'value' attribute (as 'value' attribute is used by default when not explicitly defined) of <parm> XML section with 'name' attribute equal to 'cond'.

The value is read from <parm> section which is a child section of <parms>, which is a child of <exec>, ....

Example 2:

SET &X=READXML("hos jcl_old job exec(pgm='IKJEFT01')(2) dd parms parm(name='DISP')",
               "SHR")

This example returns a value of 'value' attribute of <parm> XML section with name='DISP'.

This <parm> XML section must be a child of the first <parms> section of the first<dd> section in 2nd <exec> child section of <hos><jcl_old><job> that has pgm attribute equal to 'IKJEFT01'.

In case nothing matches the path then 'SHR' is returned.

The following syntax diagram should be clear enough for understanding the syntax:

See also the syntax o String.

SYSPLEX

Returns the sysplex where the job runs.

SYSTEM

Returns the system where the job runs.

USER

Returns a name of the user, which has submitted the job.

Functions that can be used to control objects created by SmartJCL.

ADDINSTREAM

Functions that can be used to control objects created by SmartJCL.

Adds an instream line(s) to current JCL statement at specified position

ARCHIVEDD

Returns a DD name where the output is created by JCL reformat. Available values are JUPJCLO, SRIJCLO, SRISYSO

ARCHIVESYSTEM

Returns the target system, where the currently processed member is copied by Procman and which is written to Procman's archive. The function returns a valid value only if it has been previously set by SETARCHIVESYSTEM func-tion. Otherwise it returns an empty string.

ARCHIVETYPE

Returns a type of the data stored in the actual member. Available types are JCL, PROC, SYSIN

CONTEXT

Returns a list with information about the context in which the actual JCL statement is located (job name, step name, dd name, program, level, ...).

Example:

DO(NEXTJCLSTMT());
    CALL SAY(stmt()!!':'!!stmtname(), context());
DO(END);

This function if useful for debugging, but values in the list that is returned can also be used for example in filters or IF expressions. The sample above can for example print the following output:

 DD:FILE1
 [
   JOBNAME => PRCTEST,
   JOBPOS => 1,
   STEPNAME => STEP0,
   STEPPOS => 1,
   DDNAME => DB,
   PGM => IEFBR14,
   PROC => ,
   INSTREAM => FALSE,
   PROCLEVEL => 0,
   INCLUDELEVEL => 0
 ]

CREATEMEMBER

This function allows you to create additional files in PRX script. Files created this way are written to SRIJCLO (jobs and procedures) and to SRISYSO (sysin members). Every created member is also recorded in HOSXOUT member, which instruct PHP program how to read and store members from SRIJCLO and SRISYSO. There are several variants of CREATEMEMBER function, depending on the mode of operation.

Moves or copies one or more steps from the current JCL member to an external member. As a result new members are stored to Procman archive. The moved/copied steps are reformatted, they are constructed from their parameter lists and not from original lines.

It can also be used for copying or moving of instream lines of the current DD statement when TYPE equals 'SYSIN'. In this case PRX requires that the current JCL statement is DD.

Example 1:

The first call copies the first and all further steps from the current member to ABCD member in P390A.TEST dataset on SYSH_ID system. The newly created member has JCL type and is therefore stored in JCL Procman archive.

The second call moves first, second and third steps from the current member to ABCD member in P390A.TEST dataset on the same system where the current member is. The newly created member has PROC type and is therefore stored in PROC Procman archive. This kind of copying/moving is useful for splitting the original JCL to procedures. Procedures are created in external members and steps in the original job are changed so that they call them. In this case further PRX commands are needed for creating EXEC statements that call the created procedures. This is not done automatically.

The third call moves all instream lines of the current DD statement to SRISYSO DD and instructs PRX to save the data as ABCD member in P390A.TEST library.

CREATEMEMBER(‘P390A.TEST’, ’ABCD’, ’SYSH_ID’, ’JCL’,   ’COPY’, 1);
CREATEMEMBER(‘P390A.TEST’, ’ABCD’, ’’,        ’PROC’,  ’MOVE’, 1, 3);
CREATEMEMBER(‘P390A.TEST’, ’ABCD’, ’’,        ’SYSIN’, ’MOVE’);

Moves or copies selected JCL statements from the current JCL member to an external member. As a result new members are stored to Procman ar-chive. The moved/copied statements are reformatted, they are constructed from their parameter lists and not from original lines.

Example 2:

This example shows how to create additional member similar to the main one. The sample converts the source member to a format required by PROD stage and creates similar member for TEST stage. The members differ only in a jobname and a comment line in this simple example

  /* &STAGES IS A LIST OF STAGES, THAT IS ITERATED.                     
   * TO ENSURE THAT THE INPUT IS THE SAME IN EACH ITERATION             
   * SAVEORIGMEMBER MUST BE CALLED AT THE BEGINNING. IT STORES THE INPUT
   * AND ALLOWS TO RESTORE IT BY RESTOREORIGMEMBER FUNCTION AT THE END  
   * OF EACH ITERATION                                                  
   */                                                                                                                                           
SET  &STAGES=['TEST', 'PROD'];                                          
CALL SAVEORIGMEMBER();                                                  
                                                                        
  /* THIS LOOP ITERATES OVER &STAGES LIST                               
   * IT IS IMPORTANT TO HAVE THE MAIN STAGE AS THE LAST ELEMENT         
   * (I.E. THE STAGE WHOSE OUTPUT SHOULD BE PRINTED TO JUPJCLO)         
   * THIS IS BECAUSE THE STATE OF JCL TREE THAT REMAINS WHEN PRX        
   * CODE IS FINISHED IS WRITTEN TO JUPJCLO. TO CREATE ADDITIONAL       
   * MEMBERS USE CREATEMEMBER() FUNCTION, WHICH WRITES TO SRIJCLO       
   */                                                                   
FOREACH(&STAGES AS &STAGE);                                             
                                                                        
   /* IN THIS BLOCK YOU CAN MODIFY THE JCL STATEMENTS FOR TEST STAGE         
    * IN ANY WAY. IN THIS SAMPLE WE ONLY SET THE JOBNAME AND            
    * MEMBER NAME BY OVERWRITING FIRST 2 LETTERS OF THE INPUT MEMBER    
    * NAME WITH T# AND WE ADD A COMMENT LINE AT THE VERY END.           
    * FINALLY CREATEMEMBER MUST BE CALLED TO WRITE THE RESULT TO        
    * SRIJCLO                                                           
    */         
  IF(&STAGE EQ 'TEST');                                                 
    SET &HLP = 'T#'!!SUBSTR(MEMBER(), 3);                               
    DO(NEXTJCLSTMT());                                                  
      CALL FILTER STMT='JOB'                                            
           EXEC SETSTMTNAME(&HLP)                                       
           EXEC BREAK();         /* WE CAN BREAK THE LOOP HERE AS JOB   
                                  * APPEARS ONLY ONCE, SO THERE IS NO   
                                  * REASON TO ITERATE OVER ALL STMTS */ 
    DO(END);                                                            
    CALL INSSTMT('LAST','DATA','CMT',['//*TEST']);                      
    CALL CREATEMEMBER('P391D.SAMPLE1.TEST',                             
                      &HLP, 'SYSH_ID', 'JCL', 'COPY', JCLSTMT());       
                                                                       
   /* IN THIS BLOCK YOU CAN MODIFY JCL STATEMENTS FOR PROD STAGE IN ANY WAY.  
    * AS PROD IS THE LAST ELEMENT OF &STAGES LIST THEN YOUR MODIFICATION
    * PERFORMED HERE ARE WRITTEN TO JUPJCLO AUTOMATICALLY. DO NOT CALL  
    * CREATEMEMBER.                                                
    * WE ONLY SET THE MEMBER NAME AND JOBNAME BY REPLACING 1ST 2 LETTERS
    * WITH P# AND CHANGE THE OUTPUT LIBRARY. FINALLY WE ADD A COMMENT.  
    */                                                                  
  ELSEIF(&STAGE EQ 'PROD');                                             
    DO(NEXTJCLSTMT());                                                  
      CALL FILTER STMT='JOB'                                            
           EXEC SETVAR('HLP', 'P#'!!SUBSTR(MEMBER(), 3))                
           EXEC SETSTMTNAME(&HLP)                                       
           EXEC SETMEMBER(&HLP)                                         
           EXEC BREAK();                                                
    DO(END);                                                            
    CALL INSSTMT('LAST','DATA','CMT',['//*PROD']);                      
    CALL SETLIBRARY('P391D.SAMPLE1.PROD');                              
  IF(END);                                                                                                                       

   /* RESTORE THE ORIGINAL STATE OF JCL IF A NEXT ITERATION FOLLOWS.
    * DO NOT DO IT FOR THE LAST STAGE, AS YOUR CHANGES IN THIS      
    * STAGE WOULD BE LOST AND WOULD NOT APPEAR IN JUPJCLO           
    */                                                              
  IF(&STAGE NE 'PROD');                                             
    CALL RESTOREORIGMEMBER();                                       
  IF(END);                                                          
FOREACH(END);                                                       

Creates a member from a content stored in a list or in a string. If list is used then it can contain either strings or JCL statement objects. If it contains strings then they are written to the output file exactly like they are specified. If you pass JCL statements in the list then the result is reformatted. JCL statements are objects created for example by JCLSTMT or STEPSTMT functions.

Example 3:

When the current statement is DD and when some instream lines exist then these instream lines are stored into ABCD member in P391D.TEST dataset on SYSH_ID system. The data are stored to SYSIN procman archive. After the member is created the instream lines are removed from the original JCL (by assigning empty list).

CALL
FILTER
    STMT='DD',
    TEST=COUNT(INSTREAM()) GT 0
EXEC CREATEMEMBER('P391D.TEST', 'ABCD', 'SYSH_ID', 'SYSIN', 'DATA', INSTREAM())
EXEC SETINSTREAM([]);

DD

Returns the current DD name or an empty string is the current JCL state-ment is not DD.

This function returns only DD names of statements at levels 0. It returns an empty string if it is called when a statement of a called procedure or a statement of included member is currently selected (this is possible only when procedures are resolved by SmartJCL, when PR=Y option is set).

DDLIST

Returns a list filled with DD names of the current step. The list is empty is there are no DD names in the step or if the current statement is not a part of a step.

This function returns only DD names at levels 0. It returns an empty list if it is called when a statement of called procedure or a statement of included member is currently selected (this is possible only when procedures are resolved by SmartJCL, when PR=Y option is set).

DELDD

Deletes the whole DD (including all concatenations) if the current statement is DD. If the current statement is not DD then it issues a warning.

Deletes a DD with the specified name, including all concatenations. It does nothing if such a DD is not found.

DELINSTREAM

Removes instream line at POS position from the list of existing instream lines. If POS is higher than the current number of lines then it does nothing. Pos can be negative: -1 is the last line, -2 is 2nd from the end, ...

Removes CNT instream lines starting at POS position. If POS in higher than the current number of lines then it does nothing. If POS + CNT - 1 is higher than the current number of lines then it removes all lines starting from POS. Pos can be negative.

DELORIGLINE

Removes original line at POS position from the list of existing original lines. If POS is higher than the current number of lines then it does nothing. Pos can be negative: -1 is the last line, -2 is 2nd from the end, ... It also activates the reformatting.

Removes CNT original lines starting at POS position. If POS is higher than the current number of original lines then it does nothing. If POS + CNT - 1 is higher than the current number of lines then it removes all lines starting from POS. Pos can be negative. It also activates manual reformatting.

Example 1:

CALL DELORIGLINE(-3, 3);

This example removes the last 3 original lines of the current JCL statement.

DELPARM

Deletes the current (focused) parameter. If no parameter is focused then it does nothing but issues a warning.

Deletes the specified parameter of the focused statement. If the parameter does not exist then it does nothing. If no statement is focused then it prints a warning. You can use wildcards in the name.

DELSTEP

Deletes the whole step that contains the current statement. If the statement is not inside of a step then it does nothing but prints a warning.

Deletes the whole step with specified name. If such a step does not exist then it does nothing.

DELSTMT

Deletes the current statement.

Deletes a statement with the specified name. It does nothing when such a statement is not found.

DELSUBPARM

Deletes the specified sub parameter of the current JCL statement. Both sub parameter and parameter can be numeric or strings. Numeric values can be used for positional sub parameters and parameters. String values for key-word ones.

ENTEROVR

Enters a block of overriden statements. Returns TRUE if the currently pro-cessed JCL statement has some overriden statements and in this case it enters the overriden block. Otherwise does not enter it and returns FALSE.

EXECPARM

Returns the requested parameter of EXEC statement. It returns a parameter of the EXEC that contains the current statement or of the current statement if it is EXEC. If the current statement is not a part of an EXEC then it returns an empty string.

HASINSTREAM

Returns TRUE if the current JCL statement contains at least one instream line. Returns FALSE otherwise.

HASORIGLINE

Returns TRUE if the current JCL statement contains original lines. FALSE can be returned for inserted statements, where original lines can be missing.

HASOVR

Returns TRUE is the current JCL statement contains overriden statements when SmartJCL's option PR=Y is set.

To learn more about overriden statements see Working with overriden JCL statement FAQ.

CHANGEINSTREAM

Iterates over all instream lines of the current statement and for every line checks whether it matches the mask. If yes, then such a line is replaced with REPL. The mask can contain wildcards. In this case also REPL must contain the same number and types of wildcard like MASK. It returns the number of changes.

Example 1:

CALL CHANGEINSTREAM('*P391D*', '*P390A*')

This example tries to match all instream lines of the current statement with P391D mask. If the match is successful, then the line is changed by P390A mask.

CHANGEORIGLINE

Iterates over all original lines of the current statement and for every line checks whether it matches the mask. If yes, then such a line is replaced with REPL. The mask can contain wildcards. In this case also REPL must contain the same number and types of wildcard like MASK. It returns the number of changes. This function also activates manual reformat for the statement where the change was made.

Example 1:

CALL CHANGEORIGLINE('?%CLASS?', '?W?');
CALL CHANGEORIGLINE('?%DB2GRP?', '?DN0O?');
CALL CHANGEORIGLINE('?%DUMP?', '?8?');
CALL CHANGEORIGLINE('?%CLASS?', '?T?');

Example 2:

CALL
FILTER STMT='JOB'
EXEC CHANGEORIGLINE('?%CLASS?', '?W?')
EXEC CHANGEORIGLINE('?%DB2GRP?', '?DN0O?')
EXEC CHANGEORIGLINE('?%DUMP?', '?8?')
EXEC CHANGEORIGLINE('?%CLASS?', '?T?');

Both samples to the same. The first one contains 4 CALL statements, the second one just one with a filter and 4 EXEC sections.

INCLUDELEVEL

Returns the include level of the current JCL statement. This level is greater than zero for included statements. It can be used for example for scanning statements from includes when these statements are taken into account (when #SCAN_INCLUDE equals TRUE).

Example (iteration over statements):

DEFINE #SCAN_INCLUDE=TRUE;
FOREACH(JCLSTMT() AS &STMT);
    CALL USEJCLSTMT(&STMT);
    CALL SAY('Type : '!!STMT());
    CALL SAY('Name : '!!STMTNAME());
    CALL SAY('PARM#: '!!PARMCOUNT());
    IF(INCLUDELEVEL() GT 0);
        CALL SAY('INCLUDED STATEMENT');        
    ELSE;
        CALL SAY('NORMAL STATEMENT');        
    IF(END);
FOREACH(END);

In this example a list of JCL statements is obtained by JCLSTMT function. Because #SCAN_INCLUDE is TRUE then also statements of included members are iterated. Otherwise they would be skipped. The sample demonstrates how you can check the level of included statements and do some actions depend-ing on its value. You can add any commands and function calls into IF/ELSE blocks.

INSPARM

Inserts NAME JCL parameter with VALUE value to the current statement. It does nothing if the parameter already exists.

INSSTEP

Inserts a new JCL step from JCL lines. The JCL lines must be formatted in the way in which they should appear in resulting JCL, because statements inserted this way are manually reformatted - they use the JCL lines only. The lines can contain variables, which are substituted. SEPAR is used for splitting values of these variables to lines if they contain more lines

INSSTMT

Parameter List

Definition

Inserts a new statement with a specified list of parameters.

Example

/* insert a new DD-statement with an input data-set I1 */
CALL INSSTMT("AFTER", "PARM", "DD", "I1", [["DSN", "SYSH.TEST.IN"], ["DISP", "SHR"]]);

There is also an outdated way of inserting a statement where the PARM-list is a string instead of a two dimensional list.

/* insert PARM-list as a string */
CALL INSSTMT("AFTER", "PARM", "DD", "I1", "DSN,SYSH.TEST.IN DISP,SHR");

JCL Lines

Definition

Inserts a new statement with the specified JCL lines.

Example

/* insert an OPC comment */
CALL INSSTMT("FIRST", "DATA", "CMT", ["//*%OPC SCAN"]);

JCL Lines File

Definition

Alternatively, the JCL lines can be loaded from an external file.

Example

//STEP1 EXEC VAR:TEST_VAR1
/*

/* define program call with ";" as separator */
SET &TEST_VAR1 = "PGM=IDCAMS;//SYSPRINT DD DUMMY;//SYSIN DD *;";

/* insert JCL lines from the external file */
CALL INSSTMT("AFTERJOB", "FILE", "EXEC", "SYSH.TEST(TESTMEM)", ";");

Reference Object

Generally, this function is called from the pointer of the statement it originates from. Alternatively, a statement pointer can be passed to the function call to override this behaviour. This pointer can come from e.g. the JCLSTMT- or NEXTJCLSTMT-function. Use BEFORE or AFTER as a positional parameter.

/* insert statement with parameter list */
CALL INSSTMT("AFTER", NEXTJCLSTMT(), "PARM", "DD", "I1", [["DSN", "SYSH.TEST.IN"]]);
CALL INSSTMT("AFTER", NEXTJCLSTMT(), "PARM", "DD", "I1", "DSN,SYSH.TEST.IN");

/* insert statement with JCL lines */
CALL INSSTMT("AFTER", NEXTJCLSTMT(), "DATA", "CMT", ["//*%OPC SCAN"]);
CALL INSSTMT("AFTER", NEXTJCLSTMT(), "FILE", "EXEC", "SYSH.TEST(TESTMEM)", ";");

Positional Values

Where a new statement is being inserted, depends on the positional value.

INSSUBPARM

Inserts a positional or keyword sub parameter of a positional of keyword parameter to the current JCL statement. Use a number (SPOS) if you want to insert a positional sub parameter. Use string value (SNAME) for a keyword sub parameter. Also the parameter can be referenced by its position (positional parameter) or name (keyword parameter). If the JCL parameter does not exist then it is created. If the sub parameter already exists then this function does nothing.

INSTREAM

Returns a list of instream lines of the current DD statement. The list is empty when there are no instream lines. It issues a warning when the cur-rent statement is not DD.

INSTREAMCOUNT

Returns the number of instream lines of the current JCL statement.

ISNULL

Returns TRUE if the object passed as a parameter contains NULL object. NULL object means no object, obtained for example by moving object pointer after the last one of before the first one.

JCLSTMT

JOBNAME

JOBPARM

LEAVEOVR

LIBRARY

MEMBER

NEXTJCLSTMT

ORIGLINE

ORIGLINECOUNT

ORIGPARM

OVRMODE

PARM

PARMCOUNT

PARMNAME

PARMOF

PARMVALUE

PGM

PGMLIST

PROC

PROCLEVEL

PROCLIST

REFORMAT

REPLACESUB

RESETJCLSTMT

RESTOREJCLSTMT

RESTOREORIGMEMBER

SAVEJCLSTMT

SAVEORIGMEMBER

SAVESTMT

SETARCHIVE

SETARCHIVEDD

SETARCHIVESYSTEM

SETARCHIVETYPE

SETINSTREAM

SETLIBRARY

SETMEMBER

SETORIGLINES

SETPARM

SETSTMTNAME

SETSUBPARM

SOURCELIBRARY

STEPCOUNT

STEPNAME

STEPNAMES

STEPNUM

STEPSTMT

STMT

STMTCOUNT

STMTNAME

SUBPARM

THISJCLSTMT

UPDATEPROCREF

UPDATEREF

USEJCLSTMT