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 IBM Z Workload Scheduler 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 IBM Z Workload Scheduler 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 IBM Z Workload Scheduler 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 IBM Z Workload Scheduler (CREATE request).

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

IBM Z Workload Scheduler 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. IBM Z Workload Scheduler 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.

IBM Z Workload Scheduler recognizes these TP names:
EQQTRK
Supplied by trackers that communicate with the Z controller through APPC
EQQAPI
Supplied by user programs (ATPs) that communicate with IBM Z Workload Scheduler 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 IBM Z Workload Scheduler 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 IBM Z Workload Scheduler 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. IBM Z Workload Scheduler checks security for every request to ensure that authority has not been changed.
  • IBM Z Workload Scheduler places inbound requests GET, PUT, or DEL, on the general services (GS) queue, or calls the subsystem interface (SSI) for CREATE requests. IBM Z Workload Scheduler 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, IBM Z Workload Scheduler 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 IBM Z Workload Scheduler is stopped, all conversations are deallocated.

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