NEXTGRP— Retrieve the Next Group in an SCLM Hierarchy

The NEXTGRP service returns the name of the next group in a given hierarchy. For a given group, the next group is returned in the SHARED pool variable ZSNXTGRP. An indicator whether the group is key or non-key is returned in SHARED pool variable ZSNGPKEY. The possible values for ZSNGPKEY are KEY for key groups, and NONKEY for non-key groups.

Command invocation format


>>-FLMCMD--NEXTGRP,project--,-+---------+--,group--------------->
                              '-prj_def-'           

>--,-+---------+-----------------------------------------------><
     '-dd_msgs-'

Call invocation format


>>-lastrc:=FLMLNK('NEXTGRPb',sclm_id--,group--,dd_msgs);-------><

ISPF interface panel

Figure 1. NEXTGRP Service panel

   Menu  SCLM  Utilities  Help
 ──────────────────────────────────────────────────────────────────────────────
                   SCLM FLMCMD NEXTGRP Service - Entry Panel

 SCLM Library Input:
    Project . . . SCLMTEST
    Alternate . .         
    Group . . . . DEV1    


 DD Name for output data set:
    Error message data set           (Blank to write messages to the terminal)









 Command ===>                                                                  
  F1=HELP      F2=          F3=END       F4=DATASETS  F5=FIND      F6=CHANGE
  F9=SWAP     F10=LEFT     F11=RIGHT    F12=SUBMIT

Parameters

project: The project name. The maximum parameter length is 8 characters.
prj_def: The project definition name to be used for NEXTGRP. It defaults to the project parameter. The maximum parameter length is 8 characters.
sclm_id: An SCLM ID associated with a given project and project definition. The INIT service generates the SCLM ID. The maximum parameter length is 8 characters.
group: The group for which the "next" group is to be found. The maximum parameter length is 8 characters.
dd_msgs: The ddname indicating the destination of the messages generated by the NEXTGRP service. The maximum parameter length is 8 characters.

Return codes

Other return codes might be produced by the FLMCMD or the FLMLNK processor. See SCLM service return codes for more information.

Possible return codes are:

0: Normal completion. NEXTGRP completed successfully. Variables are set.
4: Warning condition. The group is already the top group. No variables are set.
8: Error condition. Invalid project, prj_def, or group name.
12: Severe error condition. SCLM might not produce messages because there was an error invoking the NEXTGRP module. For some conditions, messages are available.

Example of command invocation

The following REXX exec begins at group USER and finds each successive group in the hierarchy defined by the SCLM7010 alternate of the SCLM70 project.

/* REXX exec to find the next groups in a hierarchy     */
TRACE off
address ispexec
group = 'USER'
done = 'false'
address 'TSO' 'alloc fi(ddm) da(sclm.msgs) shr mod'
do until done = 'true'
   'select cmd(FLMCMD NEXTGRP,SCLM70,SCLM7010,'group',ddm)'
   if rc > 0 then
      do
        done = 'true'
      end
   else
     do
       'vget (zsnxtgrp,zsngpkey) shared'
       say 'For group' group 'the next group is' zsnxtgrp zsngpkey
       group = zsnxtgrp
    end
end
address 'TSO' 'free fi(ddm)'

Executing this example produces this output:

For group USER the next group is STGE KEY
For group STGE the next group is DEV KEY
For group DEV the next group is INT KEY
For group INT the next group is REL KEY
For group REL the next group is BASE KEY

Example of call invocation

Note: This example shows general syntax. Call invocations are language-specific. See Sample programs using SCLM services for specific examples.

This program fragment uses the NEXTGRP service to find the group that USER promotes into. The variables ZSNXTGRP and ZSNGPKEY are VDEFINEd to local program variables, and the values set by the NEXTGRP service are retrieved from the shared pool by the VGET service. The example assumes that the START and INIT services have already completed successfully, so that the SLMID value is valid. The ddname DDMSGS has been allocated to a data set with valid characteristics.

CALL FLMLNK('NEXTGRP ',SLMID,'USER ',DDMSGS)
    RETCODE(R15);
    EVAL(8),' ',' ');
CALL ISPLINK ('VDEFINE ', 'ZSNXTGRP', ZSNXTGRP, 'CHAR ',
    EVAL(8),' ',' ');
CALL ISPLINK ('VDEFINE ', 'ZSNGPKEY', ZSNGPKEY, 'CHAR ',
CALL ISPLINK ('VGET ', 'ZSNGPKEY', 'SHARED ');
CALL ISPLINK ('VGET ', 'ZSNXTGRP', 'SHARED ');