Object variables

Some commands that read data from the databases or plans have an OBJECT keyword to create a set of object variables that enables programmatic access to all the fields within the object that was accessed.

Object variables are all prefixed with the at sign (@) followed by the object name. The number sign (#) is used as a prefix to indicate a count of subordinate elements. The hyphen character is then used to separate the rest of the elements of each object.

There are three kinds of object variables:

LIST

Object variables that create a count of each database or plan record converted into an object, and then a numerically suffixed object for each record found.

For example, the keyword OBJECT(MYOBJ) creates @MYOBJ, which will contain the number of records identified. Then, each record will have object variables beginning with the object name with a numeric suffix, such as @MYOBJ1-ADID, @MYOBJ2-ADID, and so on.

Though not generated from a LIST, the object for SELECT CPUSRF is similar to LIST because can return up to 100 user fields. For example, the command @USRF returns the number of user fields selected. The command @USRF1-CPUFNAME returns the name of the first user filed selected.

The following example shows another use of the LIST object variable:

VARSUB SCAN                          
LIST AD ADID-EQ(DH*) OBJECT(MYAPPS)  
DO I = 1 TO !@MYAPPS                 
   DISPLAY @V(@MYAPPS!I.-ADID)       
END

SELECT

Object variables that represent a single record in the database or plan.

For example, the keyword OBJEXT(MYOBJ) creates object variables beginning with the object name, such as @MYOBJ-ADID. The exception to this is SELECT CPUSRF, which returns an object like a LIST request.

FILE

Object variables that represent a sequential file structure.

The object variable returns the number of rows, and each row is represented by the object name followed by a hyphen (-) and row number. For example, @MYOBJ-1 shows row 1 of the file.

Understanding the structure of the database and plan objects is crucial to understand the syntax of the object variables, because they represent the structure of the records.

HCL Workload Automation for Z records can have up to three levels of information (segments). The common segment is always level one, but then most records have at least a second level, and some of those might also have a third level.

For example, in an application ADCOM is at level 1. Then there can be multiple ADRUN (run cycles) and ADOP (operations) at level 2. Finally, ADOP could have many level 3 sub segments, for example ADDEP (dependencies) and ADSR (special resources). The record structures can be seen in the relationship diagrams in the Batch Loader section.

You access data at level 1 as follows:

@<object>-<field>

where:

<object>: Name of the object that was set in the OBJECT keyword.
<field>: Name of the field.

For example, to obtain the application name of an AD record @MYOBJ-ADID, the number of objects for each second-level segment can be accessed as follows:

@<object>-#<segment2>

where:

<object>: Name of the object that was set in the OBJECT keyword.
<segment2>: Name of the second level segment.

To obtain the number of operations @MYOBJ-#ADOP, access data at level 2 as follows:

@<object>-<segment2>-<n2>-<field>

where:

<object>: Name of the object that was set in the OBJECT keyword.
<segment2>: Name of the second level segment.
<n2>: Sequence number of the second level segment.
<field>: Name of the field.

To obtain the operation number of the second operation

@MYOBJ-ADOP-2-ADOPNO

, the number of objects for each third level segment can be accessed as follows:

@<object>-<segment2>-<n2>-#<segment3>

where:

<object>: Name of the object that was set in the OBJECT keyword.
<segment2>: Name of the second level segment.
<n2>: Sequence number of the second level segment.
<segment3>: Name of the third level segment.

To obtain the number of special resources for the second operation


     @MYOBJ-ADOP-2-#ADSR

, data at level 3 can be accessed as follows:

@<object>-<segment2>-<n2>-<segment3>-<n3>-<field>

where:

<object>: Name of the object that was set in the OBJECT keyword.
<segment2>: Name of the second level segment.
<n2>: Sequence number of the second level segment.
<segment3>: Name of the third level segment.
<n3>: Sequence number of the third level segment.
<field>: Name of the field.

To obtain the special resource name of the third resource of the second operation @OBJ-ADOP-2-ADSR-3-ADSRN, you can display the complete object structure of any record type by using the SHOW OBJECT command.

In the following example, the SHOW OBJECT(CL) command shows all the available object variables for a calendar with n showing where sequence numbers fit into the syntax:

08/22 10.47.39 EQQI200I SHOW OBJECT(CL)                      
08/22 10.47.39 EQQI601A Object: @OBJ-CLNAME                  
08/22 10.47.39 EQQI601A Object: @OBJ-CLDAYS                  
08/22 10.47.39 EQQI601A Object: @OBJ-CLSHIFT                 
08/22 10.47.39 EQQI601A Object: @OBJ-CLDESC                  
08/22 10.47.39 EQQI601A Object: @OBJ-CLVERS                  
08/22 10.47.39 EQQI601A Object: @OBJ-CLLDATE                 
08/22 10.47.39 EQQI601A Object: @OBJ-CLLTIME                 
08/22 10.47.39 EQQI601A Object: @OBJ-CLLUSER                 
08/22 10.47.39 EQQI601A Object: @OBJ-CLLUTS                  
08/22 10.47.39 EQQI601A Object: @OBJ-#CLSD                   
08/22 10.47.39 EQQI601A Object: @OBJ-CLSD-n-CLSDDATE         
08/22 10.47.39 EQQI601A Object: @OBJ-CLSD-n-CLSDSTAT         
08/22 10.47.39 EQQI601A Object: @OBJ-CLSD-n-CLSDDESC         
08/22 10.47.39 EQQI601A Object: @OBJ-#CLWD                   
08/22 10.47.39 EQQI601A Object: @OBJ-CLWD-n-CLWDDAY          
08/22 10.47.39 EQQI601A Object: @OBJ-CLWD-n-CLWDNUM          
08/22 10.47.39 EQQI601A Object: @OBJ-CLWD-n-CLWDSTAT         
08/22 10.47.39 EQQI601A Object: @OBJ-CLWD-n-CLWDDESC         
08/22 10.47.39 EQQI299I Statement completed - RC=0 (00000014)

The VARSET VARIABLE keyword allows loop variables to be used as subscripts to cycle through values within an object.

The following example shows a simple loop cycling through each job name in a application object:

DO X = 1 TO @MYOBJ-#ADOP
   VARSET JOB VARIABLE(@MYOBJ-ADOP-!X-ADOPJN)
   DISPLAY !JOB
END

FILE objects are a list of records that can be processed in many ways. They are created by commands such as READ or by the SAVELIST keywords in LIST.

Finding specific rows, this example returns only the rows that contain Are we there:

VARSUB SCAN                                                     
READ IEBGENR.SYSUT2 SOURCE(SYSOUT) OBJECT(MYOBJ) CLIP(1)        
DO FOREVER                                                      
   VARSCAN MYOBJ TARGET(Are we there) CURSOR(RX,CX) 
                 ACTION(LEAVE)  
   DISPLAY @V(@MYOBJ-!RX) 
END

Filtering rows, this example returns only rows that do not start with the character W nor I:

VARSUB SCAN                                                         
READ IEBGENR.SYSUT2 SOURCE(SYSOUT) OBJECT(MYOBJ) CLIP(1)            
DO RX = 1 TO !@MYOBJ                                                
   VARSCAN MYOBJ FILTER(NE) TARGET(W,I) CURSOR(RX,CX) 
                 COLS(001,001) ACTION(ITERATE)              
   WRITE OUTDATA "@V(@MYOBJ-!RX)"                                   
END

Note:

If the object variable does not exist, the resolution fails in accordance with the VARFAIL setting or the VARSUB statement. As well as basic syntax, this applies also to the sequence numbers. For example, @MYOBJ-ADCOM-2-ADOPNO is not resolved if at least 2 operations do not exist in the object. The #<segment> elements can be used to determine how many of each object exists.
Field names and segment names for each object can be obtained from the EQQFLALL member of the Workload Automation Programming Language member.
Object variables depend on the HCL Workload Automation for Z version you are using. The SHOW OBJECT command lists the variables that are allowed for your current version of HCL Workload Automation for Z.
When an object variable is created from a Current Plan Operation command, there will be an entry found by the identification arguments. To process only the rows that were selected by the filter arguments, the object has an @FILTER attribute, which contains a list of the item numbers returned by the filter arguments.
For example:
```
VARSUB SCAN (!)
VARSET LOOPMAX = WORDS(@V(@CPO-@FILTER))
   DO X = 1 TO !LOOPMAX 
   VARSET Y = WORD(@V(@CPO-@FILTER),@V(X))
   DISPLAY "IA="||@V(@CPO!Y.-CPOPIA) 
END 
```