EQQUSIN parameters

Your program passes parameters to EQQUSIN in an APP buffer. Register 1 must point to the address of the buffer and the high-order bit must be on. The format of the buffer is the same as that used to communicate with Tivoli Workload Scheduler for z/OS through the application programming interface (API).

You can invoke EQQUSIN on z/OS systems where Tivoli Workload Scheduler for z/OS is installed. The request is sent through the subsystem interface (SSI) to Tivoli Workload Scheduler for z/OS. The return code from the call to the SSI is returned in register 15.

EQQUSIN supports multiple requests in the same buffer. The buffer can contain these sections:

APP

Fixed section - identifies the buffer

APPOBJ

Object section - identifies the object (event type)

APPSEL

Selection section - contains a field name that is used in locating one or more instances of the object

APPVAL

Selection value section - contains a field value that is used in locating one or more instances of the object

APPFLD

Field section - identifies the field to update in the selected instance of the object

APPDAT

Data section - contains a new value for each APPFLD section.

Figure 3 is an example of the layout of a buffer. This request uses 2 selection fields to locate an object and updates 1 field in the selected object. The arrows show the buffer parts that each section type points to. APP and APPOBJ point to related sections using triplet fields, which specify the offset, the length, and the number of the section type. APPSEL uses offset and length fields to point to an APPVAL section. All offsets are relative to the start of the buffer (offset 0).

Figure 3. EQQUSIN buffer example

Each section is described here in more detail.

APP - fixed section

The buffer that your program passes to EQQUSIN must contain a fixed section and it must be the first section in the buffer. It identifies the buffer, its size, the default request type, and points to object sections. The buffer must contain only 1 fixed section, even if multiple requests are passed in the same buffer.

The fixed section has this format:

In the fixed section:

APPDESC

Is the block descriptor and has the value APP.

APPVER

Is the version number and has the value 02.

*

Offset 6 (X'6'). Set this reserved field to binary zeros (X'00').

APPTYPE

Is the eye-catcher and has the value DIA.

APPFLAGS

Set this reserved field to binary zeros (X'00').

APPTOTSZ

Is the total size of the buffer.

APP_TYPE

Is the request type that is the default for all requests. It is used if you do not provide a value for APPOBJ_TYPE in an object section of the buffer. If you set this field to blanks (X'40'), you must specify a request in each object section of the buffer. Only CREATE is valid for EQQUSIN.

APP_OBJ_TRIPLET

Contains the offset to the first APPOBJ section, the length of all sections, and the number of sections.

APP_RETCODE

Is the return code that is set by EQQUSIN. In the call to EQQUSIN, set this field to binary zeros (X'00'). For more information, see Return codes and reason codes generated by EQQUSIN.

APP_RSNCODE

Is the reason code that is set by EQQUSIN. In the call to EQQUSIN, set this field to binary zeros (X'00'). For more information, see Return codes and reason codes generated by EQQUSIN.

APP_ERR_OFF

Is set by EQQUSIN when APP_RSNCODE indicates an error that has an offset associated with it. It is the offset in the buffer where a verification error was found. In the call to EQQUSIN, set this field to binary zeros (X'00').

*

Offset 48 (X'30'). Set this reserved field to binary zeros (X'00').

APPTOKEN

Is a value that your program can set to uniquely identify a buffer. It could be, for example, a time stamp. APPTOKEN can be useful if you invoke EQQUSIN through the API and there is more than one active request from your ATP at a time.

*

Offset 72 (X'48'). Set this reserved field to binary zeros (X'00').

APPOBJ - object section

This section identifies the event type you want to report to Tivoli Workload Scheduler for z/OS. The EQQUSIN buffer must contain an object section. It can contain more than one object section, but all object sections must be in contiguous storage; that is, they must follow one another. The part of the buffer containing object sections is pointed to by the APP_OBJ_TRIPLET in the fixed section. APPOBJ itself points to APPSEL, APPFLD, and APPDAT sections.

The object section has this format:

In the object section:

APPOBJ_NAME

Is the event type you want to report to Tivoli Workload Scheduler for z/OS. You can specify these object names:

CP_OPER_EVENT

Current® plan operation status. This is equivalent to the OPSTAT TSO command.

CP_OPINFO_EVENT

Current plan operation user data. This is equivalent to the OPINFO TSO command.

CP_SR_EVENT

Current plan special resource. This is equivalent to the SRSTAT TSO command.

BACKUP_EVENT

Backup request. This is equivalent to the BACKUP TSO command.

CP_WS_EVENT

Current plan workstation. This is equivalent to the WSSTAT TSO command.

APPOBJ_KEY_TYPE

Is the key type, which must be SAME for EQQUSIN. If you set this field to blanks (X'40'), SAME is used by default.

APPOBJ_FLD_TRIPLET

Contains the offset to the first APPFLD section, the length of each section, and the number of sections. Set these fields to binary zeros (X'00') when the object is BACKUP_EVENT.

APPOBJ_SEL_TRIPLET

Contains the offset to the first APPSEL section, the length of each section, and the number of sections.

APPOBJ_DAT_TRIPLET

Contains the offset to the first APPDAT section, the length of all sections, and the number of sections. Set these fields to binary zeros (X'00') when the object is BACKUP_EVENT.

APPOBJ_TYPE

Is the request type. Only CREATE is valid for EQQUSIN. If you set this field to blanks (X'40'), you must specify CREATE in the APP_TYPE field of the fixed section.

APPOBJ_RET

In the call to EQQUSIN, set this field to binary zeros (X'00'). No return code is generated in the object section for a CREATE request.

APPOBJ_RSN

In the call to EQQUSIN, set this field to binary zeros (X'00'). No reason code is generated in the object section for a CREATE request.

APPOBJ_AUTH

Set this field to blanks (X'40') in the call to EQQUSIN. It is not updated for a CREATE request.

APPSEL - selection section

This section identifies a particular field in the object type. The buffer must contain a selection section. APPSEL is pointed to by its object section and must itself point to an APPVAL section where a selection value is specified. To identify a particular instance of an object, you might need to specify more than one APPSEL for each APPOBJ. The selection sections for a particular APPOBJ must be in contiguous storage.

The selection section has this format:

In the selection section:

APPSEL_NAME

Is a field name in the object. Specifying selection criteria describes the names that you can specify for each object type.

APPSEL_OPER

Is a comparison operator. Only equal to (EQ or =) is valid for EQQUSIN.

*

Offset 18 (X'12'). Set this reserved field to binary zeros (X'00').

APPSEL_VALUE_OFF

Is the offset to the APPVAL section.

APPSEL_VALUE_LEN

Is the length of the APPVAL section.

APPVAL - selection value section

This section contains a selection value for the field identified in APPSEL. APPVAL is pointed to by APPSEL and must be included. One APPVAL is required for each APPSEL.

The selection value section has this format:

APPFLD - field section

Each field section identifies a field in the selected object that you want to update; for example, the status of an operation in the current plan. APPFLD is not used when the object name is BACKUP_EVENT but is required for all other object names. Field sections are pointed to by the APPOBJ_FLD_TRIPLET in the object section. You can specify more than one APPFLD for each APPOBJ, but all field sections for a particular APPOBJ must be in contiguous storage.

The field section has this format:

In the field section:

APPFLD_NAME

Is the name of the field. Specifying object fields to update describes the fields that you can specify for each object type.

APPFLD_LEN

Is the length of the field and is used in identifying the value in APPDAT for this field.

APPFLD_TYPE

Is the data type. EQQUSIN ignores any value in this field.

APPDAT - data section

The data section is always the last section in the buffer. It contains the new values for the fields identified in the APPFLD sections. The values must be in the same order as their corresponding APPFLD sections. Only one APPDAT is required for each APPOBJ.

The data section has this format: