APPC (PP)

The APPC (PP) subtask lets you connect to programs running on any Systems Application Architecture® (SAA®) platform, and any other platforms that conform to CPI-C protocol, which support Advanced Program-to-Program Communications (APPC). APPC is the term used to refer to an implementation of Systems Network Architecture (SNA) for logical unit (LU) type 6.2.

The application programming interface (API) is provided to enable your application transaction program (ATP) to establish a conversation with the HCL Workload Automation for Z subsystem. The API uses a subset of Common Programming Interface for Communications (CPI-C) calls, send and receive buffer mappings, and a call-sequence protocol. Your programs access the HCL Workload Automation for Z address space data by providing calls to the APPC API. You can regard the set of APPC verbs as a programming language that you can write conversations in. The HCL Workload Automation for Z API lets your own programs:
  • Extract information about the current plan (GET request)
  • Update or add current-plan operations (PUT request)
  • Delete operations in the current plan (DEL request)
  • Report events to HCL Workload Automation for Z (CREATE request).

For more information about the API, refer to Driving HCL Workload Automation for Z. For more information about CPI-C, see Common Programming Interface: Communications Reference in the Systems Application Architecture® (SAA®) library.

HCL Workload Automation for Z is an APPC transaction scheduler; the scheduler name is the same as the subsystem name. By associating the scheduler with a logical unit in the APPCPMnn member of SYS1.PARMLIB, all allocate requests directed to this LU are passed to the subsystem. HCL Workload Automation for Z then schedules a partner transaction program (TP) in its own address space. The originating TP issues a request and waits for the complete reply, before issuing a new request or deallocating the conversation.

HCL Workload Automation for Z recognizes these TP names:
EQQTRK
Supplied by trackers that communicate with the controller through APPC
EQQAPI
Supplied by user programs (ATPs) that communicate with HCL Workload Automation for Z through the API.

The APPC subtask is attached by the subsystem task. The subtask creates a new queue and table with one entry for each conversation. This entry contains data received from APPC about this conversation and parameter list areas, including the event control block (ECB), used for all asynchronous requests.

APPC and HCL Workload Automation for Z interface in this way:
  • The queue server contains a work-to-do loop, which waits on an ECB list. Initially, this ECB list contains a stop-ECB and a queue-ECB. The HCL Workload Automation for Z tracker attaches and detaches APPC.
  • Inbound allocation messages are placed on the APPC queue (APPQ) by the APPC cross-system coupling facility (XCF) message exit. When this message is detected on the queue, a new entry is added to the conversation table, and the ECB is added to the ECB list.
  • The subtask interfaces with the system security product through SAF RACROUTE calls, using the security token and local LU name. If the user does not have read or update access, the request is rejected immediately and the conversation deallocated with security_invalid. HCL Workload Automation for Z checks security for every request to ensure that authority has not been changed.
  • HCL Workload Automation for Z places inbound requests GET, PUT, or DEL, on the general services (GS) queue, or calls the subsystem interface (SSI) for CREATE requests. HCL Workload Automation for Z issues receive requests until state_received=send, before placing a request block on the GS queue or calling the SSI. All other entries in the table are checked for posted ECBs and the program then returns to a WAIT state.
  • For GET, PUT, or DEL requests, GS places the requested data on the APPC queue (APPQ). In case of error, GS generates an error return code and reason code.
  • APPC builds an outbound APP buffer. When all requested data is sent, the program returns to a WAIT state. Processing continues until the subtask is stopped or the conversation ends (state_received=deallocate_normal). The entry in the table is deleted and the ECB list is rebuilt. This also happens if severe errors occurring during the conversation.

If APPC fails, HCL Workload Automation for Z deallocates the conversation and deletes the entry in the table. You are informed of this situation, and should mask this event from your end-user by initiating a new allocate before sending a new request. If HCL Workload Automation for Z is stopped, all conversations are deallocated.

HCL Workload Automation for Z supports many conversations. The table is retained across APPC subtask sessions. Requests outstanding at the time APPC is closed are deallocated.