Application Program Examples
The COBOL programmer normally does not have access to data spaces, sysplex communications or cross systems event handling. Matrix © provides an entry point for the COBOL programmer, MXSTUB, which provides the applications programmer the ability to create, access and monitor, data spaces and events, and an interface which interprets data spaces as large scale tables, arrays and matrices. As the dataspaces which form the base of Virtual Work Areas can potentially be resident anywhere in the SYSPLEX these interfaces also handle all intra-systems and cross-systems access.
The following code example shows a COBOL program which obtains two virtual work areas, one shared and one private. It then reads and writes data in the shared virtual work area. The only reason for obtaining a private Virtual Work Area is to show it can be done. To download example source code, go to our download page.
Conceptual representation of the COBOL program
All programs need to copy the definition of the parameter list for the Application Programming Interface (API). MXPLIST contains all of the key words and structures needed to access and use the services of Matrix. This is copied into the working storage section of the COBOL program. A 20 character token is also defined to place a work area token into.
The first thing an application does is communicate with Matrix © to obtain an access token. This token is placed in the MATRIX-ACCESS_TOKEN for future access to Matrix. If a different working storage area is used later for the MATRIX-REQUEST-MSG, say in a subroutine, the token must be communicated to the routine and placed in MATRIX-ACCESS-TOKEN of the new message.
Work areas are public unless specifically made private. In this example a public work area of 3.2 Gigabytes is created. This work area named VWA1 will be accessible to all programs that have attached to Matrix © on all systems that Matrix © ia running on.
This 200 megabyte private work area has the same name as the public one. Private work areas are entirely within the address space of the application program and may have any name, including a name that is in use as a public work area. When a token is not used to identify a Virtual Work Area, the MATRIX-PRIVATE flag makes the distinction between a public and private work area on all API calls.
To access the work area for I/O a work area token is needed. This is obtained by connecting to the work area. In this case the application is gaining access to the public work area VWA1.
With the token, data can be written to the work area, no matter where it is resident. The work area could potentially be on this system, in this or another address space. It could be on another system, or it could be mirrored on all systems. The WS-DATA-AREA is within the working storage of this program.
With the token, data can be read from the work area into working storage. When the read completes, the actual number of bytes placed in the destination is returned in MATRIX-ACTUAL-LEN-READ.
When an application no longer needs access to a work area, it disconnects from the work area.
When a work area is no longer needed it can be deleted.
