Introduction
Brian Wade
VM Development
28 Oct 1998
Table of Contents
Server-Wide Initialization and Termination
Introduction
The Reusable Server Kernel is an execution infrastructure for a CMS-based server program. It solves problems repeatedly encountered in the construction of such servers. Namely, the RSK provides assistance in all of the following areas:
- Multithreading
- Heterogeneous connectivity
- Authorization
- File caching
- Memory management
- Anchors
- Worker machine management
- Large-scale DASD I/O
- Enrollment
- Client user ID normalization
Instead of consisting solely of entry points, the RSK is in fact a CMS-based server program. To use it, you attach your own business-specific logic to the RSK's execution infrastructure. When you use the RSK, you write only logic that applies to the particular business problem you are trying to solve. The RSK supplies the rest of what's necessary to let your server run well on CMS.
This workbook provides supplementary, illustrative information for specific RSK topics. It is intended to be used together with the book VM/ESA Reusable Server Kernel Programmer's Guide and Reference, which is part of the VM/ESA library.
Module Build
This discussion assumes you have your text decks ready. Among your text decks should be included:
- The deck that defines RSKMAIN, your server's entry point. Maybe that's RSKMAIN TEXT.
- Text decks for the services you wrote - their initialization, service, and termination entry points.
You might have supplied additional text decks that contain other parts of your server. For example, such decks might contain the code for long-running threads you create in your RSKMAIN.
Build your module in usual CMS fashion. Some remarks:
- You will need to GLOBAL some text libraries:
- BKWLIB
- RSK library
- DMSPSLK
- Supplemental RSK library
- DMSAMT
- CMS/MT text library
- VMMTLIB
- CMS/MT text library
- VMLIB
- CMS CSL stub library
- CMSSAA
- CMS SAA stub library
- You will need INCLUDE commands only if the loader won't pick up your text decks automatically.
- You need to include VMSTART by hand.
Here is a sample sequence of commands. In this example, text files RSKMAIN, MYINIT, MYSERV, and MYTERM comprise the application.
GLOBAL TXTLIB BKWLIB DMSPSLK DMSAMT VMMTLIB VMLIB CMSSAA LOAD RSKMAIN ( CLEAR DUP AUTO LIBE NOINV FULLMAP RLDSAVE INCLUDE MYINIT ( NOCLEAR DUP AUTO LIBE NOINV FULLMAP RLDSAVE INCLUDE MYSERV ( NOCLEAR DUP AUTO LIBE NOINV FULLMAP RLDSAVE INCLUDE MYTERM ( NOCLEAR DUP AUTO LIBE NOINV FULLMAP RLDSAVE INCLUDE VMSTART ( NOCLEAR DUP AUTO LIBE NOINV FULLMAP RLDSAVE RESET VMSTART GENMOD MYSERVER ( MAP STR
When the build is done, you will have MYSERVER MODULE and a load map.
Run-Time Environment
Each module you supply must be prepared to handle the RSK run-time environment. This environment is nothing more than a simple procedure entry and exit linkage scheme that makes it unnecessary to call CMSSTOR for save areas or automatic storage. No other traditional run-time services (exception handling, for example) are provided.
Roughly, the registers are used like this:
- R1
- Pointer to OS Type I parameter list
- R12
- Run-time anchor block pointer
- R13
- Save area pointer
- R14
- Return address
- R15
- Module entry point
Macro SSPRLG implements the procedure entry linkage. Some remarks:
- You use R0 to pass SSPRLG the number of bytes you need for automatic storage. This number must be a multiple of 8. The number you pass in R0 should include 120 bytes for the RSK's use.
- SSPRLG returns the address of the new save area in R2.
- Your automatic storage area (the storage you requested via R0) starts at offset 120 (hex X'78') into the new save area. (The first 120 bytes are used by the RSK.)
Here is an example:
RSKMAIN CSECT , RSKMAIN AMODE 31 RSKMAIN RMODE ANY STM 14,12,12(13) Save registers LR 11,15 Establish base register USING RSKMAIN,11 LA R0,DSASIZE Number of bytes needed SSPRLG Get save area LR 15,13 R15 = A(prev DSA) LR 13,2 R13 = A(my DSA) ST 15,4(,13) Write my back pointer ST 13,8(,15) Write prev's fwd pointer LM 15,2,16(15) Restore R15-R2
Procedure exit is simple as well:
L R13,4(,R13) R13 = A(prev DSA) LA R0,DSASIZE Auto storage size SSEPIL Release it L R14,12(,R13) Get return address LM R0,R12,20(R13) Restore rest of registers BR R14 Return to caller
Do whatever you want between entry and exit, but if you call some other module, make sure R12-R15 are set up correctly.
Finally, note that the run-time environment is implemented by module BKWRTE MODULE. You must have this module on one of the accessed file modes prior to starting your server.
BKWRTE MODULE is a CMS/MT language environment manager. CMS loads BKWRTE as a nucleus extension just prior to starting your module and calls entry points inside BKWRTE as part of its management of the threads in your server. Each of the following actions results in CMS calling BKWRTE:
- Process creation: BKWRTE does nothing.
- Process deletion: BKWRTE does nothing.
- Thread creation: BKWRTE does nothing.
- Passing control to a new thread: BKWRTE allocates storage to contain the save area chain for the new thread and sets up the structures necessary to permit this storage to be extended later if necessary. It then sets the registers according to the RSK's linkage conventions and passes control to the thread's entry point.
- Thread deletion: BKWRTE releases the thread's save area storage.
Server-Wide Initialization and Termination
Module Entry Point
Your code gets control at entry point RSKMAIN. Your RSKMAIN is passed an OS Type I parameter list pointed to by R1. The parameter list contains:
- Offset
- Usage
- 0
- A(CMS extended parameter list)
- 4
- A(CMS tokenized parameter list)
- 8
- A(SCBLOCK)
So, if you need to refer to any of those data areas, you can do so. The RSK doesn't do anything with any of those parameter lists.
The RSKMAIN you supply has a few jobs:
- It performs server-wide initialization, such as adjusting the virtual machine configuration, reading your own configuration or tailoring file, or creating threads or other objects (queues, mutexes) that should exist for the life of your server.
- It identifies, or binds, one or more services. These services, identified by name, are the core of your server.
- It calls ssServerRun to run the server program. When control returns from ssServerRun, the server has ended.
- It performs any server-wide cleanup.
- It returns to its caller.
Warning |
---|
You must bind all of your services before you call ssServerRun. |
RSK APIs available to RSKMAIN:
- ssServiceBind
- ssServerRun
The rest of the RSK APIs are not available because the RSK does not set up its execution environment (control blocks, vectors, etc.) until you call ssServerRun.
Example
@PROCESS ENVIRONMENT(VM/ESAOS) OPT(MAX); 00001000 00002000 /*********************************************************/ 00003000 /* */ 00004000 /* sample application... appl writer just supplies */ 00005000 /* entry point RSKMAIN and we do the rest. */ 00006000 /* */ 00007000 /* note runtime environment as */ 00008000 /* illustrated by PL/X procedure options */ 00009000 /* */ 00010000 /*********************************************************/ 00011000 00012000 rskmain: procedure 00013000 ( 00014000 pl_epptr, /* A(eplist) */ 00015000 pl_tpptr, /* A(tplist) */ 00016000 pl_scptr /* A(SCBLOCK) */ 00017000 ) 00018000 options 00019000 ( 00020000 id /* generates identifier */ 00021000 reentrant /* no static data pls */ 00022000 amode(31) /* 31-bit addresses */ 00023000 rmode(any) /* can reside anywhere */ 00024000 datareg(13) /* R13 is stack ptr */ 00025000 savearea(120) /* size of a save area */ 00026000 stack('SSPRLG ','SSEPIL ') /* hi-perf auto stg mgmt */ 00027000 ); 00028000 00029000 /* passed parameters */ 00030000 declare 00031000 pl_epptr pointer(31), 00032000 pl_tpptr pointer(31), 00033000 pl_scptr pointer(31); 00034000 00035000 /***********************************************/ 00036000 /* macros */ 00037000 /***********************************************/ 00038000 00039000 ?RegEqu; 00040000 %include syslib(ssplxsrv); 00041000 %include syslib(sstbind); 00042000 00043000 /***********************************************/ 00044000 /* automatic storage */ 00045000 /***********************************************/ 00046000 00047000 declare 00048000 00049000 /* work variables */ 00050000 p pointer(31), 00051000 00052000 /* return and reason codes */ 00053000 rc fixed(31), 00054000 re fixed(31); 00055000 00056000 /***********************************************/ 00057000 /* protect the RAB */ 00058000 /***********************************************/ 00059000 00060000 respecify (r12) restricted; 00061000 00062000 /******************************************************************/ 00063000 /* run our tests */ 00064000 /******************************************************************/ 00065000 00066000 /******************************************************************/ 00067000 /* do a bunch of ssServiceBind calls 00068000 /******************************************************************/ 00069000 00070000 /*******************************/ 00071000 /* bind the ECHO service */ 00072000 /*******************************/ 00073000 00074000 p = 0; 00075000 call ssServiceBind 00076000 ( 00077000 rc, 00078000 re, 00079000 c_ech_myname, 00080000 length(c_ech_myname), 00081000 p, 00082000 addr(ep_ech_svthread), 00083000 addr(ep_sst_term), 00084000 ss_srv_srvtype_normal 00085000 ); 00086000 if (rc^=ss_srv_rc_success ) then 00087000 return code (-1); 00088000 00089000 /*******************************/ 00090000 /* bind the SGEXER service */ 00091000 /*******************************/ 00092000 00093000 p = 0; 00094000 call ssServiceBind 00095000 ( 00096000 rc, 00097000 re, 00098000 c_exr_myname, 00099000 length(c_exr_myname), 00100000 p, 00101000 addr(ep_exr_svthread), 00102000 addr(ep_sst_term), 00103000 ss_srv_srvtype_normal 00104000 ); 00105000 if (rc^=ss_srv_rc_success ) then 00106000 return code (-1); 00107000 00108000 /*******************************/ 00109000 /* bind the HTTP service */ 00110000 /*******************************/ 00111000 00112000 p = 0; 00113000 call ssServiceBind 00114000 ( 00115000 rc, 00116000 re, 00117000 c_htt_myname, 00118000 length(c_htt_myname), 00119000 p, 00120000 addr(ep_htt_svthread), 00121000 addr(ep_sst_term), 00122000 ss_srv_srvtype_normal 00123000 ); 00124000 if (rc^=ss_srv_rc_success ) then 00125000 return code(-1); 00126000 00127000 /******************************************************************/ 00128000 /* now run the server program */ 00129000 /******************************************************************/ 00130000 00131000 call ssServerRun ( rc, re ); 00132000 00133000 /******************************************************************/ 00134000 /* return to caller */ 00135000 /******************************************************************/ 00136000 00137000 /* all done */ 00138000 return code (re); 00139000 00140000 end rskmain; 00141000 00142000
PROFILE RSK
Shortly after you call ssServerRun, the RSK drives Rexx program PROFILE RSK. This is the RSK's profile file, and herein is where you do the work necessary to configure your server, start services, and perform other operator commands.
Entry conditions for PROFILE RSK:
- If you parse arg, you'll see the command line that started your server module.
- Default subcommand handler is ADDRESS RSK, a subcom that interprets RSK operator commands.
You should do several things in PROFILE RSK:
- Take care of basic initialization chores, such as linking and accessing appropriate disks, starting a log file, or whatever.
-
Use the RSK's CONFIG command to set whatever
configuration variables need setting, such as:
- Names of important RSK files, such as authorization files or the user ID mapping file
- The user ID of your system's RSCS machine
- The size of the CP APPLDATA buffer
- Any other variables appropriate for your application
- Issue the RUNSERV command. This activates the RSK's built-in services and line drivers and starts your server running.
-
Issue line driver commands to connect your bound
services to various line drivers. The following considerations
apply:
- TCP/IP: service's port number, adapter address, and number of sockets
- UDP/IP: service's port number, adapter address, and number of concurrent requests
- APPC/VM: service's transaction program name, resource type, and maximum number of concurrent clients
- Spool: service's filename
- Subcom: service's prefix
- IUCV: service's CMSIUCV exit name and maximum number of concurrent clients
- MSG: service's prefix
- CONSOLE: service's prefix
You will want to issue line driver commands to start both the RSK's built-in services (the operator command handlers) and the services you supplied. Be careful to put these commands into PROFILE RSK in the correct order.
- Issue the WAITSERV command to wait for the server to finish.
- When WAITSERV returns, do whatever cleanup chores are appropriate and then return to your caller. The return code you specify is returned to your RSKMAIN as the reason code returned by ssServerRun. Your response in RSKMAIN will probably be to reflect the return code onward via R15.
Configuration Parameters
The RSK defines a number of configuration parameters that control the way it operates. These parameters fall into a few broad categories:
- They name certain important data files the RSK uses while it runs.
- They describe whether the RSK is to perform authorization checking on the operator commands submitted to it.
- They control the configuration of the monitor data the RSK collects.
- They govern what the RSK is to do if it is unable to map a client's user ID from something transport-specific to something transport-independent.
- They govern how certain RSK line drivers are to behave when said line drivers are confronted with client input that appears otherwise unprocessable.
- They control the amounts of memory used by various portions of the RSK.
All of these parameters are set via the operator command CONFIG.
For example, the AUTHCHECK_ family of parameters controls whether the RSK's operator command processors are to perform authorization checking on the commands they handle. These parameters are:
- Parameter
- Controls the...
- AUTHCHECK_AUTH
- AUTH service
- AUTHCHECK_CMS
- CMS service
- AUTHCHECK_CACHE
- CACHE service
- AUTHCHECK_CONFIG
- CONFIG service
- AUTHCHECK_CP
- CP service
- AUTHCHECK_LD
- The RSK's line drivers
- AUTHCHECK_SERVER
- SERVER service
- AUTHCHECK_SGP
- SGP service
- AUTHCHECK_USERID
- USERID service
- AUTHCHECK_WORKER
- WORKER service
The formal documentation contains a table explaining all of the configuration parameters and how they are used. You should take time to review the table and become familiar with the configuration parameters and what they do. You will be able to set up a successful PROFILE RSK only if you first understand how to set these configuration variables.
Example
/* */ /********************************************************/ /* */ /* test profile for Reusable Server Kernel */ /* */ /* remember that when this gets control, the default */ /* command environment is ADDRESS RSK */ /* */ /* You have to customize this to your environment */ /* */ /* (C) Copyright 1998 International Business */ /* Machines, Incorporated. All Rights Reserved. */ /* */ /********************************************************/ /* parse arg what say 'Args: /'what'/' */ sampledir = 'BKW.CRADLE.TEST' /************************************************/ /* initialization things */ /************************************************/ /* grab the storage group disks */ x = diag(8,'LINK BKW 1000 1000 MW') x = diag(8,'LINK BKW 1001 1001 MW') x = diag(8,'LINK BKW 1002 1002 MW') x = diag(8,'LINK BKW 1003 1003 MW') x = diag(8,'LINK BKW 1004 1004 MW') x = diag(8,'LINK BKW 1005 1005 MW') x = diag(8,'LINK BKW 1006 1006 MW') x = diag(8,'LINK BKW 1007 1007 MW') /************************************************/ /* set names of key data files */ /************************************************/ 'CONFIG SGP_FILE SSTEST VSSSGP ' sampledir 'CONFIG UMAP_FILE SSTEST VSSUMAP ' sampledir 'CONFIG AUT_LOCATION SFS' 'CONFIG AUT_DATA_1 SSTEST VSSAUD1 ' sampledir 'CONFIG AUT_INDEX_1 SSTEST VSSAUX1 ' sampledir /* 'CONFIG AUT_LOG SSTEST VSSAUL ' sampledir 'CONFIG AUT_DATA_2 SSTEST VSSAUD2 ' sampledir 'CONFIG AUT_INDEX_2 SSTEST VSSAUX2 ' sampledir */ /************************************************/ /* set the rest of the config stuff */ /************************************************/ /* look up RSCS userid */ address command 'IDENTIFY ( LIFO' parse pull . . . . rscsid . 'CONFIG RSCS_USERID' rscsid /* set monitor data stuff */ 'CONFIG MON_PRODUCT_ID SSTEST-fnn010100' 'CONFIG MON_KERNEL_ROWS 56' 'CONFIG MON_USER_SIZE 0' /* set implicit command rerouting preferences */ 'CONFIG VM_CONSOLE ON' 'CONFIG VM_SUBCOM ON' 'CONFIG VM_MSG ON' 'CONFIG VM_SPOOL OFF' /* set unmapped userid preferences */ 'CONFIG NOMAP_APPC OFF' 'CONFIG NOMAP_IUCV OFF' 'CONFIG NOMAP_MSG OFF' 'CONFIG NOMAP_SPOOL OFF' 'CONFIG NOMAP_TCP OFF' 'CONFIG NOMAP_UDP OFF' /* set authorization memory controls */ 'CONFIG AUT_CACHE 10000' 'CONFIG AUT_FREE 1000' /* turn on authorization checking */ 'CONFIG AUTHCHECK_AUTH ON' 'CONFIG AUTHCHECK_CACHE ON' 'CONFIG AUTHCHECK_CMS ON' 'CONFIG AUTHCHECK_CONFIG ON' 'CONFIG AUTHCHECK_CP ON' 'CONFIG AUTHCHECK_ENROLL ON' 'CONFIG AUTHCHECK_LD ON' 'CONFIG AUTHCHECK_MONITOR ON' 'CONFIG AUTHCHECK_SERVER ON' 'CONFIG AUTHCHECK_SGP ON' 'CONFIG AUTHCHECK_USERID ON' 'CONFIG AUTHCHECK_WORKER ON' /************************************************/ /* run the server */ /************************************************/ 'RUNSERV' if (rc<>0) then do say 'RC='rc 'from RUNSERV' return rc end /************************************************/ /* server came up... set about making it go */ /************************************************/ /************************************/ /* start things that need to run */ /* via SUBCOM (used later herein) */ /************************************/ 'SUBCOM START APPC' 'SUBCOM START AUTH' 'SUBCOM START CACHE' 'SUBCOM START CONSOLE' 'SUBCOM START ENROLL' 'SUBCOM START IUCV' 'SUBCOM START MONITOR' 'SUBCOM START MSG' 'SUBCOM START SERVER' 'SUBCOM START SGP' 'SUBCOM START SPOOL' 'SUBCOM START TCP' 'SUBCOM START UDP' 'SUBCOM START USERID' 'SUBCOM START WORKER' /************************************/ /* start base RSK services */ /************************************/ 'CONSOLE START APPC' 'CONSOLE START AUTH' 'CONSOLE START CACHE' 'CONSOLE START CMS' 'CONSOLE START CONFIG' 'CONSOLE START CP' 'CONSOLE START ENROLL' 'CONSOLE START IUCV' 'CONSOLE START MONITOR' 'CONSOLE START MSG' 'CONSOLE START SERVER' 'CONSOLE START SGP' 'CONSOLE START SPOOL' 'CONSOLE START SUBCOM' 'CONSOLE START TCP' 'CONSOLE START UDP' 'CONSOLE START USERID' 'CONSOLE START WORKER' 'MSG START APPC' 'MSG START AUTH' 'MSG START CACHE' 'MSG START CMS' 'MSG START CONFIG' 'MSG START CONSOLE' 'MSG START CP' 'MSG START ENROLL' 'MSG START IUCV' 'MSG START MONITOR' 'MSG START SERVER' 'MSG START SGP' 'MSG START SPOOL' 'MSG START SUBCOM' 'MSG START TCP' 'MSG START USERID' 'MSG START WORKER' /* 'SPOOL START AUTH' 'SPOOL START CMS' 'SPOOL START CP' 'SPOOL START SERVER' 'SPOOL START SGP' 'SPOOL START SUBCOM' 'SPOOL START TCP' 'SPOOL START USERID' */ 'SPOOL START ECHO' /************************************/ /* start storage groups */ /************************************/ 'SGP START 0 t0 BLOCKRW NODS' 'SGP START 1 t1 BLOCKRW NODS' 'SGP START 2 t2 BLOCKRW NODS' /************************************/ /* start sample server */ /************************************/ 'ENROLL LOAD HTTPCNFG DISK 0 HTTPCNFG VSSENR' sampledir 'ENROLL LOAD HTTPMIME DISK 0 HTTPMIME VSSENR' sampledir 'CACHE CREATE HTTPFILE 32768' 'CONSOLE START ECHO' 'CONSOLE START SGEXER' 'MSG START ECHO' 'MSG START SGEXER' 'TCP START ECHO 426' 'TCP START HTTP 428' 'UDP START ECHO 526' 'UDP START HTTP 528' 'IUCV START ECHO 40' 'IUCV REPORT ON' 'APPC START ECHO GLOBAL 40 BKWG0000' 'APPC REPORT ON' 'WORKER ADD cgiserv TEST001' 'WORKER ADD cgiserv TEST002' /************************************************/ /* wait for server completion */ /************************************************/ 'WAITSERV' /************************************************/ /* do author-supplied termination logic */ /************************************************/ /* void */ return 0
Structure of A Running Server
The RSK organizes your server into a set of CMS threads. Each thread is in its own dispatch class. The following notes apply:
- Each line driver is made up of a detector for its device and a thread that processes both device activity and IPCs from your application (your service threads).
- The line drivers' detectors are:
- The IUCV, TCP/IP, UDP/IP, APPC/VM, and MSG line drivers use HNDIUCV exits to detect device activity.
- The SPOOL line driver uses an HNDIO exit.
- The CONSOLE driver uses a CMS event monitor, listening for VMCON1ECB.
- The SUBCOM line driver sets up a subcom via SUBCOM SET.
All of these detectors do basically the same thing - they capture information about the device activity and send an IPC message to the line driver's queue so as to awaken the line driver thread and thereby cause it to handle the device.
-
The line driver threads wait in QueueReceiveBlock for
messages to arrive (each line driver has its own queue). When
an IPC message arrives, the line driver thread wakes up and
handles the request:
- Device activity: handle the device activity
- Request from a service instance: handle the request
- Depending on client activity, there might be one or more instance threads running. When there is no work to do, these threads are waiting in QueueReceiveBlock. As work arrives for them, the line drivers awaken them by sending them IPC messages telling them what's happened.
- The RSK supplies certain built-in services. These, like your services, wait in QueueReceiveBlock for work to do. When work arrives, they handle it and respond through their line drivers.
Interacting with Line Drivers
There are many aspects to interacting with line drivers:
- The line driver's behavior, generally speaking
- Your initialization routine
- Your service routine
- Your termination routine
- Connecting your service to a line driver
- Use of CMS IPC
- The ssClient APIs
Line Driver Behavior
When a new client arrives, the line driver either creates a thread to handle the client or takes a thread from a free pool it maintains. In either case, the thread is caused to begin running the service entry point for the service to which the client has connected. The thread runs until your service routine returns.
This means that your service will probably be running on multiple threads simultaneously. Even the "mundane" line drivers, like CONSOLE, do this. Be prepared for this behavior.
For example, if you used ssServiceBind to define a service called MYSERV, and if you informed the UDP/IP line driver that it was to make MYSERV available on port 992, then when a datagram arrived at port 992, the UDP line driver would arrange for a thread to call MYSERV's service entry point. This would transfer control to your code.
Your service routine uses QueueReceiveBlock to learn of work needing its attention. For each received message, your code performs the appropriate action and calls QueueReceiveBlock again.
Eventually it is time for the relationship with the client to end. At this point your code sends an IPC message to its line driver to inform the line driver that the relationship is terminated. Your code then returns to its caller.
Entry Points
Your service is made up of three routines (entry points):
- An initialization routine, which the RSK drives just prior to delivering client activity to your service.
- A service routine, which the RSK drives each time it routes a client to your service. The service routine runs on its own thread and uses CMS IPC to wait for client activity.
- A termination routine, which the RSK drives when it determines that your service will not handle any more clients.
Initialization Entry Point
When it drives your initialization routine, the RSK passes your routine the following OS Type I parameter list (R1 points to this vector):
- Offset
- Use
- 0
- A(return code)
- 4
- A(reason code)
- 8
- A(S-block)
The return code and reason code are outputs which your routine must supply. If either supplied value is non-zero, the RSK will abandon its attempt to start your service. The S-block pointer is an input. The S-block is an RSK control block providing fundamental descriptive information about the service being started. See the documentation for more information.
The initialization routine's job is to perform any initialization functions that are service-specific.
Service Entry Point
Each time a client arrives, the RSK drives your service entry point on a dedicated thread. The RSK builds the following parameter list for the service entry point:
- Offset
- Use
- 0
- A(S-block)
- 4
- A(C-block)
As mentioned earlier, the S-block provides descriptive information about the particular service in question. The C-block provides descriptive information about the relationship between the client, the RSK, and the service thread (also called the instance).
The C-block is probably the most important data structure the RSK builds for the application. It contains information crucial to the correct operation of your service, such as:
- The handle of the queue the instance should use when it receives and transmits IPC messages
- The match key the instance should use when it attempts to receive IPC messages
- The message key the instance should use when it transmits messages to its line driver
- The mapped user ID of the client
- Counters showing how much data has moved through the instance
See the documentation for more information.
Termination Entry Point
When the RSK drives your termination routine, it supplies the following parameter list:
- Offset
- Use
- 0
- A(S-block)
The termination routine's job is to perform any termination functions that are service-specific.
Connecting Your Service to a Line Driver
You use a line driver's START command to connect your service to a line driver. When you connect your service to a line driver, you make it possible for your service to interact with clients who send requests to your server via the line driver's transport method.
Each RSK line driver supports a START command which nominates the service to be started and which gives transport-specific information about how the line driver is to prepare to be contacted by clients. Specifically,
- TCP/IP: service's port number, adapter address, and number of sockets
- UDP/IP: service's port number, adapter address, and number of concurrent requests
- APPC/VM: service's transaction program name, resource type, and maximum number of concurrent clients
- Spool: service's filename
- Subcom: service's prefix
- IUCV: service's CMSIUCV exit name and maximum number of concurrent clients
- MSG: service's prefix
- CONSOLE: service's prefix
You can issue these commands via PROFILE RSK, or by hand, or via some kind of programmable operator.
Use of CMS IPC
Messages to Instance
When the instance gets control, its job is to wait to be told about client activity and then process whatever client activity occurred.
The waiting is accomplished via QueueReceiveBlock. The following information will be helpful in constructing the call:
- QRB Parameter
- Source
- Queue handle
- Comes from C-block
- Match key
- Comes from C-block
When QueueReceiveBlock returns, it will supply a message in the following form:
- Field
- Use
- 0.32
- Instance's key
- 32.4
- Message type
- 0
- Message from line driver to instance
- 36.2
- Client status bits
- X'8000'
- Client has closed connection
- X'4000'
- Connection closed abnormally
- X'2000'
- Client has finished transmitting
- X'1000'
- RSK line driver is asking that you stop
- X'0800'
- New data is available from client
When you receive this message, you should act on the bits in the following way:
- If connection closed abnormally or client has closed connection or RSK line driver is asking you to stop, clean up from the handling of this client, transmit the termination message to the line driver, and return.
- If new data is available, process it, via one or more calls to ssClientDataGet. This will probably result in one or more calls to ssClientDataPut.
- If client is done sending, send any last response data to the client, clean up from the handling of this client, transmit the termination message to the line driver, and return.
- If you have not yet encountered a reason to exit, go back and do another QueueReceiveBlock.
Message to Line Driver
When the instance queues data for the client, or when the instance otherwise requires the line driver to take some action, the instance informs the line driver of this need by sending it a CMS IPC message via call to QueueSend. The message is to be built in the following way:
- 0.32
- Line driver's key (from C-block)
- 32.4
- Message type
- 1
- Message from instance to line driver
- 36.32
- Instance's key (from C-block)
- 68.2
- Instance status bits
- X'8000'
- Instance is stopping
- X'4000'
- Instance queued output for client
The message should be sent to the line driver queue as identified by the queue handle field of the C-block.
If the instance is using this message to inform the line driver that it is terminating, it should return to its caller after it transmits the message.
The ssClient APIs
When the line driver informs the instance that data are waiting from the client, the instance should respond by calling ssClientDataGet. This routine has the following features:
- You can retrieve the data destructively or non-destructively.
- You can have the data retrieved to a VM Data Space.
- You can determine how much data is waiting to be retrieved without actually retrieving anything.
- After your retrieval operation completes, you are always told how much additional data waits to be retrieved.
When your instance is ready to write to the client, it should use routine ssClientDataPut. This routine has the following features:
- The data buffer you supply can reside in a VM Data Space.
- After your output is queued, the RSK counts the number of bytes waiting to be transmitted and returns this number to you as an output.
Example
@PROCESS TITLE('BKWRST - ep_rec_svthread') 00001000 ENVIRONMENT(VM/ESAOS) OPT(MAX) FLAG(I); 00002000 00003000 /* @LIST OFF; */ 00004000 @EJECT; 00005000 00006000 */*START OF SPECIFICATION*********************************************/ 00007000 */* */ 00008000 */* PROLOGUE */ 00009000 */* */ 00010000 */* MODULE-NAME: BKWRST */ 00011000 */* */ 00012000 */* DESCRIPTIVE-NAME: ep_rec_svthread */ 00013000 */* */ 00014000 */* COPYRIGHT = */ 00015000 GENERATE;/* 00016000 * THIS MODULE IS "RESTRICTED MATERIAL OF IBM" 00017000 * 5799-EFR (C) COPYRIGHT IBM CORP. 1991 00018000 * LICENSED MATERIALS-PROPERTY OF IBM 00019000 * SEE COPYRIGHT INSTRUCTIONS, G120-2083 00020000 * 00021000 @ENDGEN;*/ 00022000 */* */ 00023000 */* STATUS: VM/ESA Version 2 Release 3.0 */ 00024000 */* */ 00025000 */* FUNCTION: service thread for generalized line-mode service */ 00026000 */* */ 00027000 */* NOTES: */ 00028000 */* DEPENDENCIES: None */ 00029000 */* RESTRICTIONS: None */ 00030000 */* REGISTER-CONVENTIONS: R1 - List of ptrs to the parameters */ 00031000 */* R12 - RAB address */ 00032000 */* R13 - dynamic storage area */ 00033000 */* R14 - Return address */ 00034000 */* R15 - Entry point address */ 00035000 */* PATCH-LABEL: None */ 00036000 */* */ 00037000 */* MODULE-TYPE: Procedure */ 00038000 */* PROCESSOR: PL/X */ 00039000 */* MODULE-SIZE: refer to assembler listing */ 00040000 */* ATTRIBUTES: MP-capable, enabled, AMODE 31, RMODE ANY */ 00041000 */* */ 00042000 */* ENTRY-POINT: see MODULE-NAME */ 00043000 */* */ 00044000 */* PURPOSE: see FUNCTION */ 00045000 */* */ 00046000 */* LINKAGE: */ 00047000 */* OS Type I call, with the addition that R12 */ 00048000 */* points to the RAB (runtime anchor block), a data structure */ 00049000 */* used for managing the stack */ 00050000 */* */ 00051000 */* INPUT: See procedure statement */ 00052000 */* */ 00053000 */* OUTPUT: See procedure statement */ 00054000 */* */ 00055000 */* EXIT-NORMAL: as follows: */ 00056000 */* */ 00057000 */* EXIT-ERROR: as follows: */ 00058000 */* */ 00059000 */* EXTERNAL REFERENCES: */ 00060000 */* */ 00061000 */* ROUTINES: */ 00062000 */* */ 00063000 */* CONTROL-BLOCKS: .... */ 00064000 */* */ 00065000 */* CALLED-BY: ...... */ 00066000 */* */ 00067000 */* SUBROUTINES: None */ 00068000 */* */ 00069000 */* ERROR MESSAGES: None */ 00070000 */* */ 00071000 */* MACROS: */ 00072000 */* */ 00073000 */* CHANGE-ACTIVITY: */ 00074000 */* */ 00075000 */* OPERATION: */ 00076000 */* */ 00077000 */* 1) */ 00078000 */* */ 00079000 */* 2) */ 00080000 */* */ 00081000 */* */ 00082000 */*END OF SPECIFICATION***********************************************/ 00083000 */* A000000-999999 NEW FOR VM/ESA Version 2 Release 3.0 @VR74PVM*/ 00084000 */********************************************************************/ 00085000 @EJECT COMPILE ASM; 00086000 00087000 ep_rec_svthread: procedure 00088000 ( 00089000 pl_sblock, /* my S-block */ 00090000 pl_cblock /* my C-block */ 00091000 ) 00092000 options 00093000 ( 00094000 id /* generates identifier */ 00095000 reentrant /* no static data pls */ 00096000 amode(31) /* 31-bit addresses */ 00097000 rmode(any) /* can reside anywhere */ 00098000 datareg(13) /* R13 is stack ptr */ 00099000 savearea(120) /* size of a save area */ 00100000 stack('SSPRLG ','SSEPIL ') /* hi-perf auto stg mgmt */ 00101000 ); 00102000 00103000 /* parameters */ 00104000 declare 00105000 pl_sblock pointer(31), 00106000 pl_cblock pointer(31); 00107000 00108000 /*******************************************/ 00109000 /* macros */ 00110000 /*******************************************/ 00111000 00112000 ?RegEqu; /* registers */ 00113000 %include syslib(vmplxmtr); /* CMS bindings */ 00114000 %include syslib(vmplxipc); /* CMS bindings */ 00115000 00116000 %include syslib(ssplxmem); /* skySgpXxx bindings */ 00117000 %include syslib(ssplxsrv); /* skyService stuff */ 00118000 %include syslib(ssplxcli); /* skyService stuff */ 00119000 00120000 %include syslib(bkwgen); /* internal bindings */ 00121000 %include syslib(bkwrec); 00122000 %include syslib(bkwusi); /* I am USERID... */ 00123000 %include syslib(bkwsrv); /* ... or SERVER... */ 00124000 %include syslib(bkwcfg); /* ... or CONFIG... */ 00125000 %include syslib(bkwtcp); /* ... or TCP... */ 00126000 %include syslib(bkwaut); /* ... or AUTH... */ 00127000 %include syslib(bkwsgp); /* ... or SGP... */ 00128000 %include syslib(bkwcp); /* ... or CP... */ 00129000 %include syslib(bkwenr); /* ... or ENROLL... */ 00130000 %include syslib(bkwmon); /* ... or MONITOR... */ 00131000 %include syslib(bkwcac); /* ... or CACHE... */ 00132000 %include syslib(bkwicv); /* ... or IUCV... */ 00133000 %include syslib(bkwwrk); /* ... or WORKER... */ 00134000 %include syslib(bkwnam); /* names of things */ 00135000 00136000 /*******************************************/ 00137000 /* based variables */ 00138000 /*******************************************/ 00139000 00140000 declare 00141000 word fixed(31) based, /* a full word */ 00142000 halfword fixed(16) based, /* a halfword */ 00143000 byte fixed(8) based, /* a byte */ 00144000 chars character(*) based; /* char string */ 00145000 00146000 /*******************************************/ 00147000 /* automatic storage */ 00148000 /*******************************************/ 00149000 00150000 declare 00151000 00152000 /* anchor stuff */ 00153000 skya pointer(31), 00154000 00155000 /* my subpool */ 00156000 my_subpool char(8), /* my subpool */ 00157000 00158000 /* rc/re for CSL calls */ 00159000 rc fixed(31), /* return code */ 00160000 re fixed(31), /* reason code */ 00161000 00162000 /* preallocated message buffers */ 00163000 mb character(length(vmss_imsg)), 00164000 rb character(length(vmss_lmsg)), 00165000 00166000 /* pointers to said buffers */ 00167000 mp pointer(31), /* msg pointer */ 00168000 rp pointer(31), /* reply pointer */ 00169000 00170000 /* stuff for QueueReceiveBlock */ 00171000 ml fixed(31), /* msg length */ 00172000 ko fixed(31), /* key offset */ 00173000 kl fixed(31), /* key length */ 00174000 suid character(8), /* sender UID */ 00175000 spid fixed(31), /* sender PID */ 00176000 reptok fixed(31), /* reply token */ 00177000 00178000 /* stuff for working off commands */ 00179000 curcmdbuf char(1024), /* cmd buffer */ 00180000 curcmdptr pointer(31), /* cmd pointer */ 00181000 curcmdlen fixed(31), /* cmd length */ 00182000 00183000 /* record of whether i made any output */ 00184000 imadeoutput fixed(31), 00185000 00186000 /* work variables */ 00187000 i fixed(31), /* work variable */ 00188000 j fixed(31), /* work variable */ 00189000 k fixed(31), /* work variable */ 00190000 p pointer(31); /* work pointer */ 00191000 00192000 /*************************************************/ 00193000 /* protect runtime */ 00194000 /*************************************************/ 00195000 00196000 respecify (r12) restricted; 00197000 00198000 /*********************************************************/ 00199000 /* CODE BEGINS HERE */ 00200000 /*********************************************************/ 00201000 00202000 call ep_get_anchor ( skya ); 00203000 00204000 /* might as well do this now */ 00205000 curcmdptr = addr(curcmdbuf(5)); 00206000 00207000 /* and decide who I am */ 00208000 call choose_subpool; 00209000 00210000 /* set up buffer pointers */ 00211000 mp = addr(mb); 00212000 rp = addr(rb); 00213000 00214000 /*****************************************************************/ 00215000 /* here's the big service loop. just do a receive, using my */ 00216000 /* instance key from the C-block as the receive key. everything */ 00217000 /* i have to pay attention to will come to me as an IPC message */ 00218000 /* keyed according to my instance key. when the receive is */ 00219000 /* complete, then examine the message further to see what I */ 00220000 /* have to do with this new piece of work. */ 00221000 /*****************************************************************/ 00222000 00223000 do forever; 00224000 00225000 /* i haven't made output yet */ 00226000 imadeoutput = 0; 00227000 00228000 /****************************************************************/ 00229000 /* receive notice of more work. */ 00230000 /****************************************************************/ 00231000 00232000 /* wait for something to do */ 00233000 call QueueReceiveBlock 00234000 ( 00235000 rc, /* return code */ 00236000 re, /* reason code */ 00237000 pl_cblock->vmss_cblock.vc_qh, /* queue handle */ 00238000 pl_cblock->vmss_cblock.vc_ikey, /* match key */ 00239000 length(vmss_cblock.vc_ikey), /* its length */ 00240000 0, /* timeout */ 00241000 mp->chars, /* msg buffer */ 00242000 length(mb), /* its length */ 00243000 ml, /* msg length */ 00244000 ko, /* key offset */ 00245000 kl, /* key length */ 00246000 suid, /* sender UID */ 00247000 spid, /* sender PID */ 00248000 reptok /* reply token */ 00249000 ); 00250000 if (rc^=vm_ipc_success) then 00251000 goto done; 00252000 00253000 /**************************************************************/ 00254000 /* process work received. */ 00255000 /**************************************************************/ 00256000 00257000 /*******************************************************/ 00258000 /* pay attention to what my line driver is telling me */ 00259000 /* in the vi_cbits field of the message it sent. it */ 00260000 /* might be telling me that something is up with my */ 00261000 /* client and that I need to do something instead of */ 00262000 /* working off the input queue. recall these bits */ 00263000 /* are: */ 00264000 /* */ 00265000 /* vi_b_cclose client has closed connection */ 00266000 /* vi_b_aclose connection closed abnormally */ 00267000 /* vi_b_newdata there is new data on queue */ 00268000 /* vi_b_cdone client is done sending */ 00269000 /* vi_b_ldstop line driver says STOP */ 00270000 /* */ 00271000 /* if the client has closed or the connection has */ 00272000 /* closed abnormally, we're done; don't even bother */ 00273000 /* working off any pending client input. */ 00274000 /* */ 00275000 /*******************************************************/ 00276000 00277000 if ( (mp->vi_b_cclose=1) | 00278000 (mp->vi_b_aclose=1) | 00279000 (mp->vi_b_ldstop=1) ) then 00280000 goto done; 00281000 00282000 if (mp->vi_b_newdata=0) then 00283000 goto cmdsdone; 00284000 00285000 /*******************************************************/ 00286000 /* work off every whole command in the client queue. */ 00287000 /*******************************************************/ 00288000 00289000 do forever; 00290000 00291000 /**************************************************/ 00292000 /* see if there is another command in the queue. */ 00293000 /**************************************************/ 00294000 00295000 /* grab command length */ 00296000 p = addr(curcmdlen); 00297000 call ssClientDataGet 00298000 ( 00299000 rc, /* return code */ 00300000 re, /* reason code */ 00301000 ss_cli_iam_instance, /* i am instance */ 00302000 pl_cblock, /* C-block ptr */ 00303000 ss_cli_method_peek, /* peek it */ 00304000 0, /* ALET */ 00305000 p->chars, /* to here */ 00306000 4, /* four bytes */ 00307000 i, /* amt given */ 00308000 j /* amt additional */ 00309000 ); 00310000 if ((rc^=0) | (i<4)) then 00311000 goto cmdsdone; 00312000 00313000 /* not all here? */ 00314000 if (j < curcmdlen) then 00315000 goto cmdsdone; 00316000 00317000 /* there's enough... grab it */ 00318000 i = curcmdlen + 4; 00319000 call ssClientDataGet 00320000 ( 00321000 rc, /* return code */ 00322000 re, /* reason code */ 00323000 ss_cli_iam_instance, /* i am instance */ 00324000 pl_cblock, /* C-block ptr */ 00325000 ss_cli_method_read, /* read it */ 00326000 0, /* ALET */ 00327000 curcmdbuf, /* to here */ 00328000 i, /* amount to get */ 00329000 j, /* amt given */ 00330000 k /* amt left */ 00331000 ); 00332000 00333000 /*******************************************************/ 00334000 /* perform the command. do_command will use the */ 00335000 /* ssClientDataPut routine to queue output for the */ 00336000 /* client, and via return code it will signal me */ 00337000 /* whether it did so. */ 00338000 /*******************************************************/ 00339000 00340000 /* handle command */ 00341000 i = curcmdlen; 00342000 00343000 select; 00344000 00345000 /* am I AUTH? */ 00346000 when (my_subpool = c_aut_subpool) 00347000 call ep_aut_do_command 00348000 ( 00349000 skya, /* big pointer */ 00350000 pl_cblock, /* my C-block */ 00351000 curcmdptr->chars, /* command buffer */ 00352000 i, /* command length */ 00353000 rc /* return code */ 00354000 ); 00355000 00356000 /* am I CACHE? */ 00357000 when (my_subpool = c_csv_subpool) 00358000 call ep_csv_do_command 00359000 ( 00360000 skya, /* big pointer */ 00361000 pl_cblock, /* my C-block */ 00362000 curcmdptr->chars, /* command buffer */ 00363000 i, /* command length */ 00364000 rc /* return code */ 00365000 ); 00366000 00367000 /* am I CMS? */ 00368000 when (my_subpool = c_cms_subpool) 00369000 call ep_cms_do_command 00370000 ( 00371000 skya, /* big pointer */ 00372000 pl_cblock, /* my C-block */ 00373000 curcmdptr->chars, /* command buffer */ 00374000 i, /* command length */ 00375000 rc /* return code */ 00376000 ); 00377000 00378000 /* am I CONFIG? */ 00379000 when (my_subpool = c_cfg_subpool) 00380000 call ep_cfg_do_command 00381000 ( 00382000 skya, /* big pointer */ 00383000 pl_cblock, /* my C-block */ 00384000 curcmdptr->chars, /* command buffer */ 00385000 i, /* command length */ 00386000 rc /* return code */ 00387000 ); 00388000 00389000 /* am I CP? */ 00390000 when (my_subpool = c_cp_subpool) 00391000 call ep_cp_do_command 00392000 ( 00393000 skya, /* big pointer */ 00394000 pl_cblock, /* my C-block */ 00395000 curcmdptr->chars, /* command buffer */ 00396000 i, /* command length */ 00397000 rc /* return code */ 00398000 ); 00399000 00400000 /* am I ENROLL? */ 00401000 when (my_subpool = c_enr_subpool) 00402000 call ep_enr_do_command 00403000 ( 00404000 skya, /* big pointer */ 00405000 pl_cblock, /* my C-block */ 00406000 curcmdptr->chars, /* command buffer */ 00407000 i, /* command length */ 00408000 rc /* return code */ 00409000 ); 00410000 00411000 /* am I IUCV or APPC? */ 00412000 when ( (my_subpool = c_icv_subpool) | 00413000 (my_subpool = c_apc_subpool) ) 00414000 call ep_icv_do_command 00415000 ( 00416000 skya, /* big pointer */ 00417000 pl_cblock, /* my C-block */ 00418000 curcmdptr->chars, /* command buffer */ 00419000 i, /* command length */ 00420000 rc /* return code */ 00421000 ); 00422000 00423000 /* am I MONITOR? */ 00424000 when (my_subpool = c_msv_subpool) 00425000 call ep_mon_do_command 00426000 ( 00427000 skya, /* big pointer */ 00428000 pl_cblock, /* my C-block */ 00429000 curcmdptr->chars, /* command buffer */ 00430000 i, /* command length */ 00431000 rc /* return code */ 00432000 ); 00433000 00434000 /* am I SERVER? */ 00435000 when (my_subpool = c_srv_subpool) 00436000 call ep_srv_do_command 00437000 ( 00438000 skya, /* big pointer */ 00439000 pl_cblock, /* my C-block */ 00440000 curcmdptr->chars, /* command buffer */ 00441000 i, /* command length */ 00442000 rc /* return code */ 00443000 ); 00444000 00445000 /* am I SGP? */ 00446000 when (my_subpool = c_sgp_subpool) 00447000 call ep_sgp_do_command 00448000 ( 00449000 skya, /* big pointer */ 00450000 pl_cblock, /* my C-block */ 00451000 curcmdptr->chars, /* command buffer */ 00452000 i, /* command length */ 00453000 rc /* return code */ 00454000 ); 00455000 00456000 /* am I TCP or UDP? */ 00457000 when ( (my_subpool = c_tcp_subpool) | 00458000 (my_subpool = c_udp_subpool) ) 00459000 call ep_tcp_do_command 00460000 ( 00461000 skya, /* big pointer */ 00462000 pl_cblock, /* my C-block */ 00463000 curcmdptr->chars, /* command buffer */ 00464000 i, /* command length */ 00465000 rc /* return code */ 00466000 ); 00467000 00468000 /* am I USERID? */ 00469000 when (my_subpool = c_uid_subpool) 00470000 call ep_uid_do_command 00471000 ( 00472000 skya, /* big pointer */ 00473000 pl_cblock, /* my C-block */ 00474000 curcmdptr->chars, /* command buffer */ 00475000 i, /* command length */ 00476000 rc /* return code */ 00477000 ); 00478000 00479000 /* am I WORKER? */ 00480000 when (my_subpool = c_wrk_subpool) 00481000 call ep_wrk_do_command 00482000 ( 00483000 skya, /* big pointer */ 00484000 pl_cblock, /* my C-block */ 00485000 curcmdptr->chars, /* command buffer */ 00486000 i, /* command length */ 00487000 rc /* return code */ 00488000 ); 00489000 00490000 /* I'm not anyone? */ 00491000 otherwise 00492000 Generate ( DC X'0000' ); 00493000 00494000 end; /* select */ 00495000 00496000 /* keep track of output */ 00497000 imadeoutput = imadeoutput + rc; 00498000 00499000 end; /* do forever */ 00500000 00501000 /*******************************************************/ 00502000 /* all commands complete. if i made output, tell */ 00503000 /* the line driver. then handle whether the line */ 00504000 /* driver is telling me to stop. */ 00505000 /*******************************************************/ 00506000 00507000 cmdsdone: 00508000 00509000 /* notify driver if needed */ 00510000 if (imadeoutput^=0) then 00511000 do; 00512000 00513000 /* build message for line driver */ 00514000 rp->vl_lkey = pl_cblock->vmss_cblock.vc_lkey; 00515000 rp->vl_type = ss_srv_msgtype_linedriver; 00516000 rp->vl_ikey = pl_cblock->vmss_cblock.vc_ikey; 00517000 rp->vl_ibits = 0; 00518000 rp->vl_b_newdata = 1; 00519000 00520000 /* tell line driver i made some output */ 00521000 call QueueSend 00522000 ( 00523000 rc, /* return code */ 00524000 re, /* reason code */ 00525000 pl_cblock->vmss_cblock.vc_qh, /* ld queue handle */ 00526000 rp->chars, /* message buffer */ 00527000 length(rb), /* message length */ 00528000 offset(vl_lkey), /* key offset */ 00529000 length(vl_lkey) /* key length */ 00530000 ); 00531000 00532000 end; /* i made output */ 00533000 00534000 /* stop if needed */ 00535000 if (mp->vi_b_cdone=1) then 00536000 goto done; 00537000 00538000 /**************************************************************/ 00539000 /* PROCESSING OF IPC MESSAGE HAS COMPLETED */ 00540000 /**************************************************************/ 00541000 00542000 end; /* do forever */ 00543000 00544000 /*****************************************************************/ 00545000 /* end of big service loop */ 00546000 /*****************************************************************/ 00547000 00548000 done: 00549000 00550000 /* emit 'I stopped' message */ 00551000 rp->vl_lkey = pl_cblock->vmss_cblock.vc_lkey; 00552000 rp->vl_type = ss_srv_msgtype_linedriver; 00553000 rp->vl_ikey = mp->vi_ikey; 00554000 rp->vl_ibits = 0; 00555000 rp->vl_b_stopack = 1; 00556000 00557000 /* and ship it to my line driver */ 00558000 call QueueSend 00559000 ( 00560000 rc, /* return code */ 00561000 re, /* reason code */ 00562000 pl_cblock->vmss_cblock.vc_qh, /* queue handle */ 00563000 rp->chars, /* message buffer */ 00564000 length(rb), /* message length */ 00565000 offset(vl_lkey), /* key offset */ 00566000 length(vl_lkey) /* key length */ 00567000 ); 00568000 00569000 /* and return! */ 00570000 return code(0); 00571000 00572000 /*****************************************************************/ 00573000 /* local procedures implemented as macros */ 00574000 /*****************************************************************/ 00575000 00576000 %include syslib(plxdll); 00577000 %include syslib(bkwrcs); 00578000 00579000 end ep_rec_svthread; 00580000 00581000
Anchors
The RSK provides a simple callable anchor facility that lets the server author set and query the value of a server-wide anchor word. This facility complements the function available through CSL routine ThreadSetUserData.
The envisioned use for the RSK's facility is that early on in the life of the server, the author's code will call ssAnchorSet to install the value of the anchor word. This anchor word would probably be the address of some main control block. At other times as necessary, the author's code would call ssAnchorGet to retrieve the value of the anchor word, thereby obtaining (for example) the address of the main control block.
Routine ssAnchorGet also returns the address and length of the CP APPLDATA buffer the RSK maintains for the server. The author's code can place important counters or other values into the monitor buffer and they will be collected in APPLDATA records as part of CP's monitor data processing.
APIs
- ssAnchorSet: set value of anchor word
- ssAnchorGet: retrieve value of anchor word and address of user monitor buffer
Example
/* bindings */ %include syslib(ssplxanc); /* automatic variables */ declare rc fixed(31), re fixed(31), anchor pointer(31), monbufptr pointer(31), monbuflen fixed(31); /* to set the anchor */ call ssAnchorSet ( rc, re, anchor ); /* to retrieve the anchor and the monitor info */ call ssAnchorGet ( rc, re, anchor, monbufptr, monbuflen );
Memory Management
The RSK provides a callable memory API that front-ends CMS's CMSSTOR facility. This API offers the additional feature that it can allocate and release storage in VM Data Spaces. Use of VM Data Spaces is subject to any limits imposed by the server's CP directory entry (statement XCONFIG ADDRSPACE).
APIs
ssMemoryCreateDS
To use the RSK's memory API with VM Data Spaces, the first step is to create a "subpool" to represent the data space. Here is an example call:
%include syslib(ssplxmem); declare rc fixed(31), re fixed(31), subpool char(8), pagecount fixed(31), storkey fixed(31), optcount fixed(31), optarray(4) fixed(31), asit char(8), alet fixed(31); subpool = 'MYDSPACE'; pagecount = 256 * 16; /* 16 MB */ storkey = 0; optcount = 0; /* if we wanted to supply a DMSSPCC option array, */ /* we'd do so via the OPTCOUNT and OPTARRAY parms */ call ssMemoryCreateDS ( rc, /* return code */ re, /* reason code */ subpool, /* subpool name */ pagecount, /* num of pages */ storkey, /* storage key */ optcount, /* option count */ optarray, /* option array */ asit, /* DS ASIT */ alet /* DS ALET */ );
If the call is successful, the RSK will have created the data space and will be ready for you to allocate storage from it. Keep track of the ALET because you will need it to refer to the buffers you allocate.
ssMemoryAllocate
You can use ssMemoryAllocate to allocate and release storage in:
- Data spaces you created via ssMemoryCreateDS, or
- Global subpools you create explicitly via SUBPOOL CREATE, or
- Global subpools you create implicitly by first mention via call to ssMemoryAllocate.
ssMemoryAllocate supports doubleword-aligned and page-aligned requests and also supports variably-sized allocation.
%include syslib(ssplxmem); declare rc fixed(31), re fixed(31), subpool char(8), min fixed(31), max fixed(31), amtgot fixed(31), storptr pointer(31); subpool = 'MYDSPACE'; min = 32; /* at least 32 bytes */ max = 1024; /* as much as 1 KB */ call ssMemoryAllocate ( rc, /* return code */ re, /* reason code */ min, /* min needed */ max, /* max wanted */ subpool, /* subpool name */ ss_mem_align_page, /* alignment reqt */ storptr, /* storage ptr */ amtgot /* amt obtained */ );
ssMemoryRelease
The only warning here is that you should release only storage you acquired via call to ssMemoryAllocate. If you went directly to CMSSTOR, go directly there to release.
%include syslib(ssplxmem); declare rc fixed(31), re fixed(31), subpool char(8), amtgot fixed(31), storptr pointer(31); subpool = 'MYDSPACE'; call ssMemoryRelease ( rc, /* return code */ re, /* reason code */ amtgot, /* amt to release */ subpool, /* subpool name */ storptr /* storage ptr */ );
ssMemoryDelete
Use this to delete subpools you created via call to ssMemoryCreateDS or manipulated via call to ssMemoryAllocate.
%include syslib(ssplxmem); declare rc fixed(31), re fixed(31), subpool char(8); subpool = 'MYDSPACE'; call ssMemoryDelete ( rc, /* return code */ re, /* reason code */ subpool /* subpool name */ );
Commands
In front-ending CMSSTOR, the RSK keeps a cache of storage ready for giving out via ssMemoryAllocate. CMSSTOR "thinks" this storage is allocated, of course.
There is a threshold governing how much storage the RSK will cache in this way. If the free storage cache grows too large, the RSK will do releases to CMSSTOR.
The threshold is set via the CONFIG MEM_MAXFREE command. This threshold applies on a per-subpool basis. Refer to the formal documentation for more information.
Block-oriented DASD
The RSK provides a block-oriented model for reading and writing minidisks, whether CKD or FBA. The purpose of the APIs and associated commands is to give the server access to a large, high-speed pool of persistent storage blocks. The server is free to impose whatever logical structure makes sense for the problem at hand. The minidisks read and written via this facility do not contain useful CMS file systems - that is, this facility is not able to provide access to files stored on CMS minidisks.
Minidisks used by the RSK's DASD model must be formatted at 4 KB and reserved. The RSK provides no facility for performing these initialization steps automatically.
The RSK organizes minidisks into sets called storage groups. Storage groups have the following properties:
- Each storage group can contain up to 16 TB (X'100000000' 4 KB blocks), spread over up to 13,000 minidisks.
- The RSK supports up to 1024 storage groups.
- The server operator can request that
I/O to the storage group be performed via any of
these means, on a per-storage-group basis:
- MAPMDISK: the RSK maps the minidisks' 4 KB blocks into the pages of one or more VM Data Spaces. To read the blocks, the RSK performs MVCL from the corresponding pages. To write the blocks, the RSK performs MVCL to the corresponding pages and then issues MAPMDISK SAVE to cause the pages to be committed.
- DIAG X'250': the RSK starts an I/O operation to one or more minidisks in the storage group and receives external interrupts informing it of the I/O's completion.
- DIAG X'A4': the RSK calls a CP API to perform I/O to the minidisks in a storage group. CP returns control to the RSK when the I/O is complete.
- I/O to a storage group is thread-synchronous and thread-blocking. By thread-synchronous we mean that the calling thread does not get control back until the I/O is complete. By thread-blocking we mean that if the virtual machine must wait for the I/O to complete, only the requesting thread waits; the virtual CPU is used to run other threads while we are waiting for the I/O to finish. (Not true if DIAG X'A4' is used.)
Figure 1 illustrates the notion of storage groups.
Storage Group 0 SG 1 SG n *-----------------------------------* *------* ... *------* | 3F0 Data Space | | | | | | 0 *------* *- *---------* | | | | | | 1 *------* -* | | pgs 0 | | | | | | | | data | *-----* | to 48 | | | | | | | | | | *- *---------* | | | | | | 49 *------* -* | | | | | | | | | | | pgs 49 | | | | | | | 2E4 *--* | to 146 | | | | | | | 0 *------* | | | | | | | | | | | | | | | | | | | | | | 2 *------* -* | | | | | | | | | | | data | | | *- *---------* | | | | | | | | *--* | | pgs 147 | | | | | | | | | | | | to 215 | | | | | | | | | | *--* | | | | | | | | | | | | *- *---------* | | | | | | | | | | more than | | | | | | 99 *------* -* | 1 DS if | | | | | | | needed | | | | | | | | | | | | | 1A32 | Disk Blks | | | | | | 0 *------* | ---- ---- | | | | | | | | | 3F0 49 | | | | | | 2 *------* -* | 2E4 98 | | | | | | | | | | 1A32 69 | | | | | | | data | *--* ---- | | | | | | | | | 216 | | | | | | 70 *------* -* | | | | | *-----------------------------------* *------* *------* ^ ^ ^ V V V *--------------------------------------------------------------* | I/O engine: | | - Read via MVCL; write via MVCL then MAPMDISK SAVE | | - APIs for I/O and admin/maint operations | | - Commands for admin/maint operations | *--------------------------------------------------------------* ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ | | | | | | | | | | *------------------------------------------------* server threads |
The grouping of minidisks into storage groups is recorded in the file pointed to by configuration parameter SGP_FILE.
When a storage group is brought online it is assigned a symbolic name. This symbolic name is how the storage group is identified in the ssSgpRead and ssSgpWrite API calls. This lets the server operator change the configuration of the storage groups without breaking programs.
Beyond this there is not a lot to say about these storage groups. There exist APIs and commands to bring storage groups online and offline, and there are APIs for performing reads and writes to storage groups.
APIs
All of these APIs are prototyped in SSASMSGP MACRO and SSPLXSGP COPY.
APIs for performing operator functions:
- ssSgpStart: brings a storage group online
- ssSgpStop: takes a storage group offline
APIs for performing I/O:
- ssSgpRead: reads blocks from a storage group.
- ssSgpWrite: writes blocks to a storage group.
Various other APIs:
- ssSgpCreate: create a new storage group
- ssSgpDelete: delete a storage group
- ssSgpQuery: obtain information about a storage group
Commands
There are analogs for most of the APIs, for example:
- SGP START: start a storage group
- SGP STOP: stop a storage group
- SGP LIST: obtain a list of storage groups
- SGP MDLIST: list minidisks of a specific storage group
The SGP service can be attached to any of the record-oriented line drivers, and then SGP commands can be issued via that line driver. For example, if we start the SGP service through the console driver, we can then type these SGP commands on the console.
Example
00001000 /* bindings */ 00002000 %include syslib(ssplxsgp); 00003000 00004000 00005000 /* variables */ 00006000 declare 00007000 rc fixed(31), 00008000 re fixed(31), 00009000 sgid char(8), 00010000 curstart fixed(31), /* zero-origin start */ 00011000 curcount fixed(31), /* num of blocks */ 00012000 bufptr pointer(31); 00013000 00014000 00015000 /* doing a write is like this... */ 00016000 call ssSgpWrite 00017000 ( 00018000 rc, /* return code */ 00019000 re, /* reason code */ 00020000 sgid, /* sg name */ 00021000 curstart, /* page number */ 00022000 curcount, /* page count */ 00023000 0, /* buffer ALET */ 00024000 bufptr->chars /* buffer itself */ 00025000 ); 00026000 00027000 00028000 /* reading pages is like this... */ 00029000 call ssSgpRead 00030000 ( 00031000 rc, /* return code */ 00032000 re, /* reason code */ 00033000 sgid, /* sg name */ 00034000 curstart, /* page number */ 00035000 curcount, /* page count */ 00036000 0, /* buffer ALET */ 00037000 bufptr->chars /* buffer itself */ 00038000 ); 00039000 00040000
File Caching
The RSK provides an API set that performs caching of CMS files read from minidisk, SFS, or BFS. Cached files are held in VM Data Spaces. The server author uses the caching capability by calling the RSK's file reading routines instead of calling the CSL (DMSOPEN, BPX1OPN) or the FS macros (FSREAD). The RSK resolves the server's read request from a VM Data Space if possible.
The caching API does more than just cache file data. Recognizing that the data are likely to be consumed in a different code page and record format than that in which they were stored, the RSK lets the opener specify translation schemes that govern how the RSK will transform the file data as it loads the data into the cache. This lets frequently-accessed files' data be transformed only once.
Details
- The server operator uses the RSK's CACHE command set to create one or more file caches. Each file cache is its own VM Data Space.
- Each cache is managed in LRU fashion.
- To open a file for reading, the server calls
ssCacheFileOpen, supplying the following
inputs:
- Name of cache to use
- Name of file to be opened
- Any relevant ESM data
- Which file system to search (minidisk/SFS or BFS)
- How to translate data read from the file
- How to expect records to be delineated in the read file
- How to organize the records in the cached file
Under some conditions, the RSK will attempt to determine whether the file resides in minidisk/SFS or in the BFS and will use the corresponding CSL routine automatically.
- ssCacheFileOpen returns several pieces of
information about the cached file:
- A token the caller can use in calling ssCacheFileRead
- The ALET and address of the cached data
The latter lets the caller go after the data without an API call if he desires (just enter AR mode and read the buffer).
- When the caller closes the file (via ssCacheFileClose), the file becomes eligible for displacement from the cache, providing no other callers have the file open.
- Regarding concurrency, a given file can be open multiple times concurrently, and multiple reads can be in progress against a given file simultaneously.
APIs
There are just a few APIs.
- ssCacheCreate: create a file cache
- ssCacheDelete: delete a file cache
- ssCacheFileOpen: cache a file
- ssCacheFileRead: read cached data
- ssCacheFileClose: close a cached file
- ssCacheQuery: obtain stats about a cache
- ssCacheXlTabSet: install a translation table
Commands
- CACHE CREATE: create a file cache
- CACHE DELETE: delete a file cache
- CACHE LIST: show a list of file caches
Example
00932000 /**************************************************/ 00933000 /* set open options based on translation type. */ 00934000 /* ssCacheFileOpen handles data conversions. */ 00935000 /**************************************************/ 00936000 00937000 num_flags = 4; 00938000 flag_names(1) = ss_cac_ofn_recmethod_fs; 00939000 flag_names(2) = ss_cac_ofn_xlate; 00940000 flag_names(3) = ss_cac_ofn_recmethod_cache; 00941000 00942000 select; 00943000 00944000 /* BINARY: do it as-is */ 00945000 when ( (filtertype(1::6) = 'binary') & 00946000 (filtertypelen = 6) ) then 00947000 do; 00948000 flag_values(1) = '00000000'x; 00949000 flag_values(2) = 0; 00950000 flag_values(3) = '01000000'x; 00951000 end; 00952000 00953000 /* ASCII: it depends */ 00954000 when ( (filtertype(1::5) = 'ascii') & 00955000 (filtertypelen = 5) ) then 00956000 do; 00957000 if (fs_type = fs_sfs) then 00958000 do; 00959000 flag_values(1) = '00000000'x; 00960000 flag_values(2) = 0; 00961000 flag_values(3) = '01020D0A'x; 00962000 end; 00963000 else 00964000 do; 00965000 flag_values(1) = '01011500'x; 00966000 flag_values(2) = 0; 00967000 flag_values(3) = '01020D0A'x; 00968000 end; 00969000 end; 00970000 00971000 /* DOS: X'0D0A' markers */ 00972000 when ( (filtertype(1::3) = 'dos') & 00973000 (filtertypelen = 3) ) then 00974000 do; 00975000 flag_values(1) = '01020D0A'x; 00976000 flag_values(2) = 0; 00977000 flag_values(3) = '01020D0A'x; 00978000 end; 00979000 00980000 /* UNIX: X'0A' markers */ 00981000 when ( (filtertype(1::4) = 'unix') & 00982000 (filtertypelen = 4) ) then 00983000 do; 00984000 flag_values(1) = '01010A00'x; 00985000 flag_values(2) = 0; 00986000 flag_values(3) = '01020D0A'x; 00987000 end; 00988000 00989000 /* CMS: insert record lengths */ 00990000 when ( (filtertype(1::3) = 'cms') & 00991000 (filtertypelen = 3) ) then 00992000 do; 00993000 if (fs_type = fs_sfs) then 00994000 flag_values(1) = '00000000'x; 00995000 else 00996000 flag_values(1) = '01011500'x; 00997000 flag_values(2) = 0; 00998000 flag_values(3) = '02020000'x; 00999000 end; 01000000 01001000 /* MODULE: it depends, due to how */ 01002000 /* OPENVM PUTBFS behaves for MODULEs */ 01003000 when ( (filtertype(1::6) = 'module') & 01004000 (filtertypelen = 6) ) then 01005000 do; 01006000 if (fs_type = fs_sfs) then 01007000 do; 01008000 flag_values(1) = '00000000'x; 01009000 flag_values(2) = 0; 01010000 flag_values(3) = '02020000'x; 01011000 end; 01012000 else 01013000 do; 01014000 flag_values(1) = '00000000'x; 01015000 flag_values(2) = 0; 01016000 flag_values(3) = '01000000'x; 01017000 end; 01018000 end; 01019000 01020000 /* CGI: this is an escape for later */ 01021000 when ( (filtertype(1::3) = 'cgi') & 01022000 (filtertypelen = 3) ) then 01023000 do; 01024000 goto giveerr; 01025000 end; 01026000 01027000 /* HIDE: refuse to serve file */ 01028000 when ( (filtertype(1::4) = 'hide') & 01029000 (filtertypelen = 4) ) then 01030000 do; 01031000 goto giveerr; 01032000 end; 01033000 01034000 /* other types - 7BIT, 8BIT, EBCDIC, etc. */ 01035000 otherwise 01036000 do; 01037000 if (fs_type = fs_sfs) then 01038000 flag_values(1) = '00000000'x; 01039000 else 01040000 flag_values(1) = '01011500'x; 01041000 flag_values(2) = 1; 01042000 flag_values(3) = '01020D0A'x; 01043000 end; 01044000 01045000 end; /* end select */ 01046000 01047000 /* set up for BFS/RFS for ssCacheFileOpen */ 01048000 01049000 flag_names(4) = ss_cac_ofn_bfs; 01050000 if (fs_type = fs_bfs) then 01051000 flag_values(4) = ss_cac_ofv_yes; 01052000 else 01053000 flag_values(4) = ss_cac_ofv_no; 01054000 01055000 /**************************************************/ 01056000 /* try opening the file now. try uppercasing if */ 01057000 /* first open fails with not_found. */ 01058000 /**************************************************/ 01059000 01060000 /* 01061000 ?DMSMSG 01062000 TEXT('Filespec &1 &2') 01063000 SUB(DEC,filespec_len,HEX4,(filespec,filespec_len)); 01064000 */ 01065000 01066000 do while (fileopen=0); 01067000 01068000 ssCacheFileOpen 01069000 ( 01070000 rc, /* return code */ 01071000 re, /* reason code */ 01072000 filcache, /* cache name */ 01073000 filespec, /* file name */ 01074000 filespec_len, /* name length */ 01075000 c, /* ESM data */ 01076000 0, /* none */ 01077000 num_flags, /* flag count */ 01078000 flag_names, /* flag names */ 01079000 flag_values, /* flag values */ 01080000 file_token, /* file token */ 01081000 cache_alet, /* cache ALET */ 01082000 file_addr, /* cache address */ 01083000 file_size, /* file size */ 01084000 file_update /* update time */ 01085000 ); 01086000 01087000 if (rc=0) then 01088000 do; 01089000 fileopen = 1; 01090000 /* 01091000 ?DMSMSG 01092000 TEXT('Date: &1') 01093000 SUB(CHAR,file_update); 01094000 */ 01095000 end; 01096000 else 01097000 do; 01098000 01099000 /* announce error */ 01100000 ?DMSMSG 01101000 TEXT('&1: RC=&2 RE=&3 from ssCacheFileOpen') 01102000 SUB(CHAR,(filespec,filespec_len),DEC,rc,DEC,re); 01103000 01104000 /* if not_found, uc and try again */ 01105000 if ( (re^=ss_cac_re_file_not_found) | 01106000 (ucfs=1) ) then 01107000 goto giveerr; 01108000 else 01109000 do; 01110000 call xlate 01111000 ( 01112000 addr(uce), 01113000 addr(filespec), 01114000 filespec_len 01115000 ); 01116000 ucfs = 1; 01117000 end; 01118000 01119000 end; /* open error */ 01120000 01121000 end; /* while */ 01122000 01123000 /* if we get here, the file is open */ 01124000 01125000
Authorization
In many situations, a server is nothing more than an access method for objects of various kinds. For example, an HTTP server is a just a server that sends files over socket connections when browsers ask for them.
When servers are acting as access methods, it is sometimes appropriate for the server to impose authorization rules on the set of clients, operations, and objects. Taken together, this set of rules describes "who can do what to whom". Typically, for each object controlled by the server, there will be a small set of rules for each authorized user, each rule listing the subset of operations the user is permitted to perform.
The RSK supports the construction and maintenance of such an authorization rule set by providing a rule base manager in the form of a set of APIs and operator commands. This rule base manager understands the abstract notions of user, object, and action, but the actual objects defined, users defined, and actions defined are left to the server designer to decide. The RSK's rule manager just relates users, objects, and actions, whatever they are defined to be. Unlike ESMs such as RACF, the RSK does not actually protect objects.
It is expected that servers needing to protect their objects will store the rule base in the RSK's rule base manager. When clients ask to perform certain operations on objects, the server can call the RSK, supplying the object name, the client name, and a vector of proposed operations. The RSK will respond with an yea/nay vector, and the server will interpret said response and either do the client's bidding or send a negative response.
Setup
The authorization rules are kept in a pair of CMS files. The pair can be stored on minidisk or in the CMS Shared File System. (Storing the files on an accessed SFS directory counts as SFS.) The setup process varies according to the storage medium you choose.
Minidisk
When the files are on minidisk, the RSK keeps twin copies of the pair (four files in all) and keeps a log file that describes which pair is up-to-date at the moment. This scheme lets the RSK recover from an incomplete update (device failure, etc.).
When you use minidisk, observe the following guidelines:
- Though you can put all five files on a single minidisk, best protection is achieved with pair 1 and the log file on one minidisk and pair 2 on another minidisk. If possible, put these two minidisks on separate packs.
- Minidisks containing authorization files must have no files open for output on them except the authorization files themselves. In fact, it would be a good idea to use these minidisks only for authorization files and not for any other purpose.
Then proceed in PROFILE RSK as illustrated in this snippet from a mythical PROFILE RSK:
/* this assumes minidisk 1 is at filemode K and */ /* minidisk 2 is at filemode L */ 'CONFIG AUT_LOCATION MINIDISK' fn = 'RULEBASE' dfile = fn 'RSKAUD' xfile = fn 'RSKAUX' 'CONFIG AUT_DATA_1 ' dfile 'K' 'CONFIG AUT_INDEX_1 ' xfile 'K' 'CONFIG AUT_DATA_2 ' dfile 'L' 'CONFIG AUT_INDEX_2 ' xfile 'L' 'CONFIG AUT_LOG ' fn 'RSKAUL K'
Shared File System
When the files are in SFS, the RSK uses SFS's work unit support to commit changes together. Thus, only one pair of files is needed and no log file is needed.
This snippet from a mythical PROFILE RSK configures the authorization data to reside in SFS:
'CONFIG AUT_LOCATION SFS' fn = 'RULEBASE' authdir = 'MYPOOL:SERVER.AUTHDATA' 'CONFIG AUT_DATA_1 ' fn 'RSKAUD' authdir 'CONFIG AUT_INDEX_1 ' fn 'RSKAUX' authdir
Users, Objects, and Actions
A user is just a 1- to 64-byte string identifying a user.
An action is just a 4-byte string identifying an action.
An object class is just a set of actions. The object class is identified by an eight-byte name. For example, object class FRED might be the set of actions READ, WRIT, EXEC, and ERAS. There is no hierarchy in these operations.
An object is a specific item that belongs to an object class. The object is identified by a 1- to 256-byte name. For example, object My Data File might belong to object class FRED and therefore would have FRED's actions defined on it.
APIs
Simple APIs
These do pretty much what you would expect.
- ssAuthCreateClass: create an object class.
- ssAuthModifyClass: modify an object class.
- ssAuthCreateObject: create an object. The object starts life with no rules associated with it.
These APIs remove objects, classes, and users from the rule base.
- ssAuthDeleteObject: delete all of the rules associated with an object, and optionally delete the object.
- ssAuthDeleteClass: delete all of the objects in a given class (including their rules), and optionally delete the class.
- ssAuthDeleteUser: find all of the rules associated with a given user and delete them.
These APIs produce listings of various kinds.
- ssAuthListClasses: produce a listing of the classes in the rule base.
- ssAuthListObjects: produce a listing of the objects in a given class (with wildcard matching).
These APIs perform various queries against the rule base.
- ssAuthQueryObject: look up the set of rules associated with the given object.
- ssAuthQueryRule: look up the rule associated with the given (object,user) pair.
The remaining APIs are complex enough to warrant their own sections.
ssAuthPermitUser
This API accepts an (object,user) pair as input, so as to identify the rule to be modified. It also accepts other input information describing how said rule is to be modified. The modification instructions are passed in as two arrays and a scalar.
Consider first the two n-element arrays. The first array contains a list of operations defined on the object's class. The second n-element array tells whether the corresponding action is to be added to or deleted from the rule. For example, consider these two three-element arrays:
op array action array -------- ------------ READ ss_aut_add_operation WRIT ss_aut_remove_operation EXEC ss_aut_add_operation
This would add READ and EXEC permissions to the rule and remove WRIT permission from the rule.
The scalar describes how the arrays are to be applied:
- Value
- Meaning
- ss_aut_add_all
- First add all defined operations to the current rule, then apply the arrays.
- ss_aut_delete_all
- First completely delete the current rule, then apply the arrays.
- ss_aut_use_arrays
- Just apply the arrays to the current rule.
With a little thought you can see how this structure lets the current rule be edited easily.
ssAuthPermitUser returns an n-element vector in response. The elements of the vector describe the results of applying the arrays:
- Value
- Meaning
- ss_aut_op_not_defined
- The operation was not defined on the object's class.
- ss_aut_op_permitted
- The operation is now permitted.
- ss_aut_op_not_permitted
- The operation is now not permitted.
- ss_aut_no_change
- The array entry did not result in a rule change.
ssAuthTestOperations
This entry point lets you test a proposed set of operations against a rule in the rule base.
The rule to be tested is identified by ordered pair (object,user).
The proposal is an n-element vector of operations you believe are defined on the object.
The response is an n-element vector of responses. Each element of the vector is one of the following scalars:
- Value
- Meaning
- ss_aut_op_permitted
- The operation is permitted.
- ss_aut_op_not_permitted
- The operation is not permitted.
- ss_aut_not_defined
- The operation is not defined on this object class.
This can be used to test many operations simultaneously. Also, this is good for locking because writes to the rule set are disabled while the test is being conducted.
Operator Commands
These parallel the API set. They all start with AUTH.
- CRECLASS: create an object class
- CREOBJECT: create an object
- DELCLASS: delete the objects in a class, and also the class itself
- DELOBJECT: delete the rules for an object, and also the object itself
- DELUSER: delete the rules for a user
- LISTCLASS: list defined classes
- LISTOBJECT: list objects in a class
- MODCLASS: modify object class
- PERMIT: change a rule
- QOBJECT: list rules for an object
Example
*COPY BKWCAU 00001000 00002000 /*********************************************************/ 00003000 /* */ 00004000 /* check_auth: checks to see whether things are OK. */ 00005000 /* if things are NOT OK then return with a nonzero rc. */ 00006000 /* */ 00007000 /* caller must include: */ 00008000 /* ssplxaut */ 00009000 /* ssplxsrv */ 00010000 /* */ 00011000 /* caller must declare: */ 00012000 /* rc fixed(31) */ 00013000 /* */ 00014000 /*********************************************************/ 00015000 00016000 check_auth: procedure 00017000 ( 00018000 ca_cblock, /* C-block addr */ 00019000 ca_sn, /* service name */ 00020000 ca_snl, /* name length */ 00021000 ca_cw, /* check word */ 00022000 ca_op /* op type */ 00023000 ); 00024000 00025000 /* parameters */ 00026000 declare 00027000 ca_cblock pointer(31), 00028000 ca_sn char(8), 00029000 ca_snl fixed(31), 00030000 ca_cw fixed(31), 00031000 ca_op char(4); 00032000 00033000 /* automatic storage */ 00034000 declare 00035000 re fixed(31), 00036000 results fixed(31), 00037000 userid_len fixed(31), 00038000 i fixed(31); 00039000 00040000 /* pretend it's OK */ 00041000 rc = 0; 00042000 00043000 /* if AUTHCHECK_LD is off or he is inside this */ 00044000 /* virtual machine, it's OK */ 00045000 00046000 if ( (ca_cw=0) | 00047000 (ca_cblock->vmss_cblock.vc_userid = '* ') ) then 00048000 return; 00049000 00050000 /*****************************************************/ 00051000 /* call to ssAuthTestOperations goes here. the call */ 00052000 /* is configured like this: */ 00053000 /* */ 00054000 /* OBJECT: name of the service being manipulated */ 00055000 /* USER: userid from C-block */ 00056000 /* ACTION: STRT or STOP */ 00057000 /* */ 00058000 /*****************************************************/ 00059000 00060000 i = 1; 00061000 do while ((ca_cblock->vmss_cblock.vc_userid(i) ^= ' ') & 00062000 (i <= 8)); 00063000 i= i + 1; 00064000 end; 00065000 00066000 userid_len = i - 1; 00067000 call ssAuthTestOperations 00068000 ( 00069000 rc, /* return code */ 00070000 re, /* reason code */ 00071000 ca_cblock->vmss_cblock.vc_userid, /* userid */ 00072000 userid_len, /* its length */ 00073000 ca_sn, /* object name */ 00074000 ca_snl, /* its length */ 00075000 1, /* op count */ 00076000 ca_op, /* op name */ 00077000 results /* results */ 00078000 ); 00079000 00080000 /* if call worked, check results */ 00081000 if (rc=0) then 00082000 if (results^=ss_aut_op_permitted) then 00083000 rc = 1; 00084000 00085000 /* and return to caller */ 00086000 return; 00087000 00088000 end check_auth; 00089000 00090000
Enrollment
Many servers face the problem of holding onto enrollment information describing the clients they serve. The RSK provides an enrollment API that lets the server hold onto this data easily. The RSK's enrollment engine holds onto enrollment records by keeping them in a VM Data Space. This lets the RSK hold onto hundreds of thousands of enrollment records using in-memory techniques.
While this engine was designed to hold enrollment records, it is really just a simple indexed access method with a single key and no wildcarding. Feel free to put it to other uses, such as holding your server's configuration parameters.
The RSK supports memory-only enrollment sets. These sets are empty each time the server starts and are never written to disk. This might be useful for tracking transient indexed sets, such as information about the set of currently-connected clients.
Details
Some notes:
- Record keys are 64 bytes long and case-sensitive.
- Record data can be up to 65,450 bytes long.
- Transactions against permanent sets are recorded in an SFS file and committed when you say so.
APIs
Operations on sets:
- ssEnrollLoad: load enrollment set from SFS into data space
- ssEnrollCommit: commit changes made to an enrollment set
- ssEnrollDrop: unload enrollment set from data space
Operations on records:
- ssEnrollRecordGet retrieve record, given key
- ssEnrollRecordInsert: insert or replace record
- ssEnrollRecordDelete: delete record, given key
Maintenance operations:
- ssEnrollList: list loaded enrollment sets
- ssEnrollRecordList: list keys in particular set
For example,
%include syslib(ssplxenr); declare rc fixed(31), re fixed(31), setname char(8), key char(64), buffer char(512), amtgot fixed(31); /* retrieve BKW's record */ setname = 'MYDIRECT'; key = 'BKW'; call ssEnrollRecordGet ( rc, /* return code */ re, /* reason code */ setname, /* set name */ key, /* key to use */ buffer, /* output buffer */ length(buffer), /* buffer size */ amtgot /* amt returned */ );
Commands
All of these start with ENROLL.
Operations on sets:
- LOAD: load enrollment set from SFS
- DROP: drop enrollment set from data space
- COMMIT: commit changes to enrollment set
Operations on records:
- GET: display contents of record
- INSERT: insert or replace record
- REMOVE: remove record from set
Maintenance operations:
- LIST: display list of loaded sets
- RECLIST: display keys from given set
Example
enroll list ENROLL Name Pages Entries InUse D K ENROLL ---- ----- ------- ----- - - ENROLL HTTPCNFG 256 3 1 0 d ENROLL HTTPMIME 256 209 6 0 d RSK> cp q spaces CP ASIT STORAGE P/S ACC SPACE IDENTIFICATION CP 36F3344000000013 128M PRV R/W MPTEST:BASE CP 36F334C000000007 1M PRV R/W MPTEST:BKW_HTTPCNFG CP 36F3350000000007 1M PRV R/W MPTEST:BKW_HTTPMIME CP 36F3340000000012 128M PRV R/W MPTEST:BKW_HTTPFILE CP BKWHCP0900I RC=0 from CP. RSK> enroll reclist HTTPCNFG ENROLL LOGGING ENROLL ROOT ENROLL FSTYPE RSK>
Worker Machines
Certain kinds of work are best done in isolation. Running CGI programs, for example, should be done in a way that an errant CGI can't destroy your server's ability to turn HTTP transactions. Recognizing this, the RSK supports the notion of worker machines and offers an API that lets the server distribute work among virtual machines.
Design points:
- The RSK organizes worker machines into classes and considers each member of a given class to be functionally equivalent.
- When you call ssWorkerAllocate, you specify the class in which you are interested. In response, the RSK selects a worker and establishes an IUCV connection to it. The RSK then arranges a C-block to represent the connection and returns the C-block address to you as an output.
- If necessary, the RSK will XAUTOLOG the worker machine for you. Further, if the worker appears hung or unresponsive, the RSK will FORCE it and re-XAUTOLOG it in an attempt to reset it.
- You can tune the worker selection logic so that the RSK will either tend to keep the logged-on set small or tend to log on as many workers as possible. Depending on the nature of your worker transactions, one of these strategies might be more appropriate than the other.
- The RSK attempts to distribute work evenly to the logged-on workers, "evenness" being evaluated as the number of IUCV connections to each worker.
- The RSK uses distributable IUCV in talking to the workers. If your systems are so configured, your workers could be on another VM system. You can suppress the RSK's FORCE and XAUTOLOG logic in this case, but you must manage the worker pool yourself.
- Your code uses ssClientDataGet, ssClientDataPut, and CMS IPC to interact with the worker, just as if the worker were a client. Notices about worker activity will appear on your line driver queue, just like notices about activity from your "real" client.
APIs
There is only one API: ssWorkerAllocate.
%include syslib(ssplxwrk); declare rc fixed(31), re fixed(31), icblock pointer(31), class char(8), ocount fixed(31), onames(4) fixed(31), ovals(4) fixed(31), wcblock pointer(31), connid fixed(31); /* set up classname */ class = 'MYWCLASS'; /* set up options array */ ocount = 2; /* i prefer an empty worker if possible */ onames(1) = ss_wrk_ofn_prefer_empty; ovals(1) = ss_wrk_ofv_yes; /* try all workers in pool */ onames(2) = ss_wrk_ofn_retry_count; ovals(2) = 0; /* now make the call */ call ssWorkerAllocate ( rc, /* return code */ re, /* reason code */ icblock, /* my C-block */ class, /* worker class */ ocount, /* option count */ onames, /* option names */ ovals, /* option vals */ wcblock, /* worker C-block */ connid /* connection ID */ ); /* if RC=0, watch for notifications in my line */ /* driver queue -- 'message type' field of IPC */ /* message will contain the connection ID */
Commands
These all start with WORKER:
- ADD: add a worker to a class
- CLASSES: shows a summary of defined classes
- DELCLASS: gets rid of a worker class
- DELETE: removes a worker from a class
- DISTRIBUTE: suppresses FORCE/AUTOLOG logic
- MACHINES: summarizes activity in a given class
- RESET: resets RSK's state memory about a class
- STATUS: status of all active worker connections
User ID Mapping
Because the RSK lets you write a service without regard for the transport technology the client uses to reach you, it is necessary for the RSK to provide some transport-independent means of identifying clients for you. If the RSK provided no such mechanism, it would be nearly impossible for you to perform authorization checking for the objects your server manages.
Said another way, because the RSK offers transport independence, a given user (person) could connect to your server over a number of different transport protocols. As the author of a transport-independent server, you would want your client to be able to access his resources with the same privileges no matter what transport technology he used to connect to you.
The RSK attempts to address this problem by having all of its line drivers map transport-specific user identifiers through a mapping file. The result of the mapping -- a single-token user identifier -- is passed to you as the identifier of the user.
The crux of the mapping support is a mapping file that contains rules about how userids should be mapped. Each record in the file has the following form:
MAP <transport> <node> <userid> <mapped_userid>where:
- Token
- Meaning
- MAP
- identifies a mapping record
- <transport>
- the transport technology to which this record applies
- <node>
- the second-order qualifier that appears in the transport-specific user identifier
- <userid>
- the first-order qualifier that appears in the transport-specific user identifier
- <mapped_userid>
- the mapped user ID that should be passed to your code
You should craft
the <transport>,
<node>, and <userid>
tokens in your mapping records according to
Table 1.
Table 1. Use of Mapping Tokens
<transport> | <node> | <userid> |
---|---|---|
TCP, UDP | dotted-decimal IP address | * |
APPC | LU name | conversation security user ID |
MSG, SPOOL, IUCV | CP node | VM user ID |
CONSOLE, SUBCOM | n/a | n/a |
Note that LISTFILE-like wildcarding (* and %) can be used in the <transport>, <node>, and <userid> fields. For example, to match all nodes starting with GDL, one could write GDL* in the <node> field.
Commands
- Use CONFIG UMAP_FILE to nominate the user ID mapping file.
- Use USERID RELOAD to have the RSK re-read the mapping file after you've changed it.
APIs
The mapping function itself is available to you via call to ssUseridMap. (Maybe you can think of another use for this besides mapping user IDs.)
Example
* Userid map file (node userid validated_userid) * File is processed from top to bottom, first match wins * APPC/VM stuff (LU name, IPVMID) MAP APPC '*USERID:* BKW BKW ; Brian Wade MAP APPC '*USERID:* DRQ BKW ; Brian Wade MAP APPC '*USERID:* BKW7 BKW ; Brian Wade MAP APPC '*USERID:* WADEB BKW ; Brian Wade * TCP/IP mapping MAP TCP 9.130.57.10 * BKW MAP TCP 9.130.57.120 * BKW2 MAP TCP 9.130.79.171 * VMWEB * userid/nodeid stuff (spool, MSG, SMSG) MAP * GDLVM7 BKW BKW ; Brian Wade MAP * GDLVM7 DRQ BKW ; Brian Wade MAP * GDLVM7 BKW7 BKW ; Brian Wade MAP * GDLVM7 WADEB BKW ; Brian Wade MAP * WSCVM BKW BKW ; Brian Wade MAP * GDLVMWEB EWEBADM BKW ; Brian Wade MAP * GDLVMWEB BKW BKW ; Brian Wade MAP * GDLVM7 DONOVANM DONOVANM ; Mike Donovan * anything that falls through MAP * * * $UNKNOWN ; Everyone else
Monitor Data
The RSK collects data describing the operation of its various subsystems and uses CP's APPLDATA facility to cause the collected data to accrue in CP monitor data records. The RSK uses a single monitor buffer, declared via DIAG X'DC'. (This will work only if OPTION APPLMON appears in the server's CP directory entry.)
The RSK divides the monitor buffer into 72-byte fragments called monitor rows. Each monitor row contains information about a specific facet of RSK operation. After the RSK's monitor rows, there is a portion of the monitor buffer called the application area. This area is reserved for the server author's use; anything written to that buffer lands in CP APPLDATA records. The server can obtain the address of the application area by calling ssAnchorGet.
The first monitor row, called the kernel row, contains enough information so that you can deduce the organization of the rest of the monitor buffer. The size of a monitor row, the number of monitor rows, and the size of the application area all appear in the kernel row.
The first eight bytes of a monitor row give a generic description of the kind of information being accrued in the row. For example, the first eight bytes might be LINEDRV to indicate that information about a line driver is being accrued. Note, though, that if the first eight bytes are zero, the row is not in use and should be ignored. The second eight bytes always contain a further qualifier of some kind - in the LINEDRV example, the second qualifier is the name of the line driver. You should refer to the formal documentation for the descriptions of all of the possible kinds of monitor buffers.
If you are writing a program to reduce or analyze the collected monitor records, you will want to know the following pieces of information about the monitor buffer:
- The first row is always the kernel row.
- Subsequent rows are either unused (as indicated by the first eight bytes being zero) or in use for a specific purpose. The specific purpose is notated in the first eight bytes of the buffer.
- From one sample to the next you will notice rows coming and going. This is just indicative of the RSK changing configuration in response to operator commands.
Commands
As regards the RSK's monitor data, there are a few commands you should know.
- CONFIG MON_KERNEL_ROWS n tells how many rows the RSK should reserve in the monitor buffer. If you reserve too few rows, the RSK will issue a message when it tries to allocate a monitor row but finds none free.
- CONFIG MON_USER_SIZE n tells how many bytes long the application area should be.
- CONFIG MON_PRODUCT_ID identifier lets you set the 16-byte product identifier the RSK uses to label the monitor buffer.
- MONITOR DISPLAY type subtype lets you display all the monitor rows matching the type and subtype you specify. This is useful, for example, for displaying all of the MEM rows if you want to see the rows having to do with subpool activity.
- MONITOR USER shows you the application area of the monitor buffer.
- SERVER MONITOR shows you the number of monitor rows and the size of the application area.
Example
server config SERVER Parameter Value SERVER --------- ----- (some stuff deleted) SERVER MON_PRODUCT_ID SSTEST-FNN010100 SERVER MON_USER_SIZE 32 SERVER MON_KERNEL_ROWS 55 (some stuff deleted) RSK> server monitor SERVER BKWSRV0301I Monitor buffer at 07E59000.00000F98, 55 rows, 7 free RSK> monitor display kernel MONITOR KERNEL at 07E59000.00000048 MONITOR D2C5D9D5 C5D34040 40404040 40404040 00000037 00000048 00000020 00000001 MONITOR 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 RSK> monitor display linedrv MONITOR LINEDRV SPOOL at 07E59558.00000048 MONITOR D3C9D5C5 C4D9E540 E2D7D6D6 D3404040 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 MONITOR LINEDRV MSG at 07E59630.00000048 MONITOR D3C9D5C5 C4D9E540 D4E2C740 40404040 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 MONITOR LINEDRV SUBCOM at 07E59708.00000048 MONITOR D3C9D5C5 C4D9E540 E2E4C2C3 D6D44040 00000000 00000020 00000000 0000023E MONITOR 00000000 000004F0 00000000 00000000 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 MONITOR LINEDRV CONSOLE at 07E597E0.00000048 MONITOR D3C9D5C5 C4D9E540 C3D6D5E2 D6D3C540 00000000 00000002 00000000 0000001D MONITOR 00000000 0000011C 00000000 00000000 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 MONITOR LINEDRV TCP at 07E59AB0.00000048 MONITOR D3C9D5C5 C4D9E540 E3C3D740 40404040 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 MONITOR 00000000 00000000 RSK> monitor user MONITOR User data at 07E59F78.00000020 MONITOR 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 RSK> CP SPOOL CONSOLE STOP CLOSE