Coding a single parameter list, multiple token areas

This variation allows you to continue a previous subcommand after you have started another. You might need to use multiple token areas when your application program is designed to support a sequence of subcommand requests like the one that follows:

Use a SEARCHVOLUME subcommand to request volume information. For example:
```
SEARCHVOLUME OWNER(userid) LIMIT(*)
```
Use a SEARCHDATASET subcommand to obtain data set information. For example:
```
SEARCHDATASET VOLUME(volser) LIMIT(*)
```
Repeat subcommands until all information for all data sets is obtained and passed back to your user.

Figure 1 shows how you can use a single parameter list and multiple tokens to identify work areas. The multiple token areas allow the flexibility of continuing a previous subcommand after starting another subcommand. Use the token you obtained from the previous subcommand when you want to continue that subcommand.

Figure 1. Single parameter list, multiple token areas

******************************************
** Start the first subcommand
******************************************
  XC    TOKEN1,TOKEN1            No resources/token yet
  LA    R4,SUBCMD1               Point to 1st subcommand
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=BEGIN,                 X
        TOKEN=TOKEN1,                                    X
        SUBCMDADDR=(R4),OUTBUFADDR=(R3)
  ...
******************************************
** Start the second subcommand
******************************************
  XC    TOKEN2,TOKEN2            No resources/token yet
  LA    R4,SUBCMD2               Point to 2nd subcommand
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=BEGIN,                 X
        TOKEN=TOKEN2,                                    X
        SUBCMDADDR=(R4),OUTBUFADDR=(R3)
  ...
******************************************
** Continue the second subcommand
******************************************
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=CONTINUE,              X
        TOKEN=TOKEN2,                                    X
        OUTBUFADDR=(R3)
  ...
******************************************
** Continue the first subcommand
******************************************
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=CONTINUE,              X
        TOKEN=TOKEN1,                                    X
        OUTBUFADDR=(R3)
  ...
******************************************
** Release resources for the first subcommand
******************************************
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=RELEASE,               X
        TOKEN=TOKEN1
  ...
******************************************
** Release resources for the second subcommand
******************************************
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=RELEASE,               X
        TOKEN=TOKEN2

Figure 1 shows how you can reuse resources. When your application program is finished with the first subcommand request, it can reuse the first token to begin a third request. When that token is reused to begin a new subcommand request, you cannot continue the previous request associated with that token.

In Figure 1, the same output buffers are used for all subcommand requests. As a result, all of the output data in the output buffer must be processed before another request can be started or continued. To avoid this situation, you might write your application program to use multiple output buffers instead of a single output buffer.

Figure 1 shows multiple releases using the OPERATION=RELEASE parameter. Instead of using multiple releases, you can specify the OPERATION=ENDALL once to free all resources associated with all tokens. See Figure 2 for an example of this method.

Note: You do not specify the TOKEN parameter when you use OPERATION=ENDALL. Your application program, however, is responsible for setting all tokens to zeros to prevent them from being reused.

Figure 2. Releasing all resources

******************************************
** Release all resources
******************************************
  EDGXCI  MF=(E,PLIST),PLISTVER=MAX,                     X
        APIADDR=APIMOD@,OPERATION=ENDALL

Your application program might encounter a resource constraint condition like short-on-storage before it issues the OPERATION=ENDALL.