The following example shows how an application uses the name/token
callable services. The application, called a server
application, offers services to users. The application resides
within a single address space, the server address
space. The application offers services to users that reside in
address spaces outside the server address space. The example assumes
the server application has already set up the cross-memory environment
that allows the users to connect to the server address space.
The server application uses name/token callable service twice during
its initialization:
- The first use is to make important information available to the
users. Before users can invoke the services of the server application,
they need to know the Program Call (PC) number that they use to switch
program processing from their primary address spaces to the server's
address space. Through IEANTCR, the server, in supervisor state, creates
a system-level name/token pair. With a system-level pair, programs
running in any address space can retrieve the token, in this case
the PC number the user must have to call the server. The invocation
that creates the name/token pair is as follows:
CALL IEANTCR,(SYSLEV,NAME,TOKEN,NOPERSIST,RETURNCODE)
The
name/token pair is not marked as persistent; users cannot retrieve
the token (that is, the PC number) if the server has terminated. If
the server is terminated or in the process of restarting, the user
will have to wait until the server is restarted before successfully
retrieving the PC number.
A user retrieves the PC number through
the following invocation:
CALL IEANTRT,(SYSLEV,NAME,TOKEN,RETURNCODE)
- The server also uses IEANTCR to create a primary-address-space-level
name/token pair. With this name/token pair, any program running in
the server's address space can use the name to retrieve the associated
token. In this case, the token contains a pointer to the application's
main data area. The invocation that creates the name/token pair is
as follows:
CALL IEANTCR,(PRIMLEV,NAME2,TOKEN2,NOPERSIST,RETURNCODE)
If
the server abnormally terminates, its recovery routine might use the
following invocation to retrieve the address of the main data area.
Note that if the recovery routine gets control before the address
space terminates, the recovery routine can retry; the name/token pair
is still retrievable until the address space completes termination.
CALL IEANTRT,(PRIMLEV,NAME2,TOKEN2,RETURNCODE)