General information about HCL Workload Automation for Z subroutines

Read this information before you use HCL Workload Automation for Z subroutines:
  • HCL Workload Automation for Z provides both individual subroutines (EQQUSINB, EQQUSINS, EQQUSINO, EQQUSINT, and EQQUSINW) and a general subroutine (EQQUSIN), which reside in the AEQQMOD0 distribution library. The subroutines can be either link-edited into the load module that they are called from or moved to an authorized library and dynamically invoked. Regardless of the method you choose, these subroutines must run either APF authorized, in PSW key 0–7, or in supervisor state. If a subroutine is called from an unauthorized environment, for example CICS®, it should be called from a user SVC. Because these subroutines do not perform input/output operations or other operations involving waits, they will not adversely affect the performance of the environment that they are called from.
  • The subroutines do not perform RACF® security checking of the data passed to them. One reason is that the event information generated by a subroutine could be used in two or more HCL Workload Automation for Z address spaces where the security rules differ. You are responsible for the security of the function. You can protect these subroutines by placing them in a protected library. Or, the program calling the subroutine can perform security checking.
  • The event information that you report has a primary function, but in many instances, you can provide extra information that can cause more updates. If you want to provide extra information through an HCL Workload Automation for Z subroutine, use EQQUSIN, which has additional parameters that are not available in the individual subroutines. EQQUSIN is a general subroutine that you can use instead of any individual subroutine. It is functionally equivalent to all HCL Workload Automation for ZTSO commands.

    If you already use individual subroutines, you can continue to use them without changes. But, they are retained only for compatibility; EQQUSIN is preferred.

  • The parameters that you pass to the subroutines are checked only for the correct format; that is, numeric fields must contain only numbers within a valid range, date fields must contain valid dates, and so on. The parameters are not checked for their validity for a particular HCL Workload Automation for Z address space. For example, a workstation name that you specify is not verified against the actual workstations that exist in a particular HCL Workload Automation for Z current plan. Also, a single event record can be generated that is used in two or more HCL Workload Automation for Z address spaces. A particular parameter (for example, the application description ID) might be valid for one address space and not another.

    If the minimum parameter requirements are met and the parameters are in the correct format, the subroutines will execute successfully and generate an event record.

    When the event is processed by the controller, it is checked for validity. If errors are found, an error message is written to the controller message log (EQQMLOG).

  • You can use the subroutines even if HCL Workload Automation for Z (in particular, the event writer subtask) is not active. Event records are still generated and placed in the event writer queue. When the event writer starts, the event records are removed from the queue and written to the event data set.
  • If, when you write a new process to use the subroutines, an invalid buffer is created, the event manager might abend on the controller receiving the event. In this case, the Event Manager must be restarted before any further testing can take place. The invalid buffer might be created in such a way that the SUBSYSTEM_NAME field is not read, even if you provide one. In this case, the Event Manager might abend on all subsystems that have a tracker active on the LPAR where you run the test.