SAVE—Lock, Parse, and Store a Member

The SAVE service locks and parses a member, and stores that member's statistical, dependency, and historical information all in one service call. The SAVE service calls the LOCK, PARSE, and STORE services.

Note: The SAVE service does not parse a member correctly if the member is packed. Make sure that the pack mode is off in the member's profile.

Before you start the SAVE service, the member must exist in the development library you specify. (The LOCK, SAVE, or STORE service can be complete for the member, but this is not necessary.) Upon completion of the SAVE service, the member has been locked and its access key has been set. (You must supply the correct access key for previously locked members.) A typical development scenario follows:

Update or create the member.
Start the SAVE service to parse the member and store the member's statistical, dependency, and historical information.

For more information about the LOCK, PARSE, and STORE services, see their service descriptions in this chapter.

Note: Use of the SAVE service causes SCLM to delete all previously stored $list_info data from the member's dependency and historical information. Each invocation of the SAVE service creates a new set of statistical, dependency, and historical information for the member.

If you need pre-existing historical information, such as user entry data, do not invoke the SAVE service. Use the LOCK, PARSE, and STORE services instead.

Command invocation format


>>-FLMCMD--SAVE,project,-+---------+--,group,type,member-------->
                         '-prj_def-'                       

>--,-+----------+--,-+------------+--,-+--------+--------------->
     '-authcode-'    '-access_key-'    '-userid-'   

                     .-Y-.                  .-C-.    .-C-.   
>--,-+----------+--,-+---+--,-+--------+--,-+---+--,-+---+------>
     '-language-'    '-N-'    '-ddname-'    '-U-'    '-U-'   

>--,-+-------------+--,-+------------+-------------------------><
     '-change_code-'    '-subproject-'

Call invocation format


>>-lastrc--:=--FLMLNK('SAVEbbbb',sclm_id--,group,type,member---->

>--,authcode,access_key--,-+-userid-+--,language--,-+-Y-+------->
                           '-'--'---'               '-N-'   

>--,ddname--,-+-C-+--,-+-C-+--,-+-Y-+--,$list_info-------------->
              '-U-'    '-U-'    '-N-'                

>--,max_prom_group--,$msg_array--,-+------------+-);-----------><
                                   '-subproject-'

ISPF interface panel

Figure 1. SAVE Service panel

   Menu  SCLM  Utilities  Help
 ──────────────────────────────────────────────────────────────────────────────
                     SCLM FLMCMD SAVE Service - Entry Panel
                                                                    More:     +
 SCLM Library:
    Project . . . SCLMTEST
    Alternate . .         
    Group . . . . DEV1    
    Type  . . . . SOURCE  
    Member  . . .         

 Authorization code  . .           (If blank, the default auth code is used)
 Access key  . . . . . .                
 User id . . . . . . . .           (If blank, your user id is used)
 Change code . . . . . .         
 Language  . . . . . . . COB     

                                      Compilation
 Mode  . .    1. Conditional          Unit Mode . . .    1. Conditional
              2. Unconditional                           2. Unconditional

 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. This parameter is used for FLMCMD only.

prj_def

The project definition name to be used for the lock, parse, and store. It defaults to the project parameter. The maximum parameter length is 8 characters. This parameter is used for FLMCMD only.

sclm_id

An SCLM ID associated with a given project and project definition. The SCLM ID is generated by the INIT service. The maximum parameter length is 8 characters. This parameter is used for FLMLNK only.

group

The group in which the lock, parse, and store are to occur. The specified group must be a development library. The maximum parameter length is 8 characters.

type

The type containing the member. The maximum parameter length is 8 characters.

member

The member to be locked and parsed, and whose accounting information is to be stored. The maximum parameter length is 8 characters.

authcode

The authorization code to be used for the lock. If you do not supply an authcode, SCLM uses default values as follows:

The authorization code from the existing member if the member being locked exists in the hierarchy
The default authorization code for the group if the member does not exist in the hierarchy.

The maximum parameter length is 8 characters.

access_key

The access key to be assigned to the member. The access key is required for any further manipulation of the member until you use the UNLOCK service to remove the access key. It defaults to blank. The maximum parameter length is 16 characters.

userid

User ID of the person requesting the SAVE service. It defaults to the current system user ID. The maximum parameter length is 8 characters.

language

The language of the member. The maximum parameter length is 8 characters. You must specify the language the first time you save a member; after that a language name is optional. If not specified, the language will default to the language already defined for the member. Specify a different language name if you wish to change the name of the language defined for the member. Parsers will be called based on the current value specified.

Y|N

Y indicates that SCLM is to copy parser listings to the ddname parameter only if parser errors occur. N indicates that SCLM is to copy all parser listings to the ddname. The maximum parameter length is 24 characters.

If the parser for the specified language does not produce a listing, specify Y. The language parsers supplied by SCLM do not produce a listing. If the parser for the specified language does produce a listing, you can specify either value. For more efficient performance, specify Y. Project-specific parsers can produce a listing. The default value for FLMCMD is Y. There is no default value for FLMLNK.

ddname

The ddname indicating the destination of the parser listings. If you specify a blank ddname, SCLM does not generate the parser listings. The maximum parameter length is 8 characters.

If the parser for the specified language does not produce a listing, specify a blank ddname. The language parsers supplied by SCLM do not produce a listing. If the parser for the specified language does produce a listing and you specified a ddname, allocate the ddname with the attributes required by the parser. Project-specific parsers can produce a listing.

C|U

Specify C to indicate that the member's statistical and dependency information is not to be saved in the event of a parser error; that is, the STORE service is not to be called if the PARSE service completes with a return code of 4. Specify U to indicate that the member's statistical and dependency information is to be saved even in the event of a parser error. The maximum parameter length is 24 characters. The default value for FLMCMD is C. There is no default value for FLMLNK.

C|U

Specify C to indicate that a compilation unit cannot be drawn down into a different member. Specify U to indicate that a compilation unit can be drawn down into a different member. The maximum parameter length is 24 characters. The default value for FLMCMD is C. There is no default value for FLMLNK.

change_code

A change_code to be added to the information obtained by parsing the member. If the member's accounting record lists the change_code, SCLM updates the date and time stamps for the existing change_code entry. The maximum parameter length is 8 characters. This parameter is used for FLMCMD only.

subproject

The name of the subproject to be assigned to the member. This parameter must only be specified if the SCLM project has been defined with subprojects. For more information about subprojects, see SCLM security.

The maximum parameter length is 8 characters.

Y|N

Y tells SCLM to verify change code records appearing in $list_info with the change code verification routine specified in the project definition. N tells SCLM not to verify change code records. The maximum parameter length is 24 characters.

This parameter is only valid for the FLMLNK call invocation. SCLM always verifies change_code records for the FLMCMD command format.

Specify N if your project definition does not specify a change_code verification routine. Ask your project manager if your project is using a change_code verification routine.

$list_info

An input or output parameter pointing to an array of records that contains change_code information. SCLM adds any change codes appearing in the array to the information it obtains by parsing the member. If you are not adding change_code information to the parser information, SCLM can pass a fullword zero buffer address. The array contains only change_code records.

SCLM deletes all information associated with the member (such as user entry data) previously stored through the STORE service with the $list_info parameter.

SCLM ignores the Date and Time Stamp fields on all change_code entries in the $list_info array. The SAVE service assigns the last change date and time from the member's accounting record to all change_codes it finds in the array. Note that SCLM does not update the array itself.

SCLM adds all change_code data listed in $list_info to the existing change_code data in the member's accounting record. If the member's accounting record already lists the change_code, SCLM updates the date and time stamps for the existing change_code entry.

This parameter is used for FLMLNK only. See Pointer parameter descriptions for more details on $list_info.

max_prom_group

An output parameter indicating the highest group in the hierarchy to which the member can be promoted. Based on the authorization code you used for the lock, SCLM determines the highest group that you can promote this member to. The maximum parameter length is 8 characters. This parameter is used for FLMLNK only.

$msg_array

An output parameter pointing to the message array. See Pointer parameter descriptions for more information about $msg_array. This parameter is used for FLMLNK only.

Return codes

Additional special services messages are written to the FLMMSGS ddname. See SCLM service messages for more information.

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.
4: Warning condition. The $msg_array parameter determines the location of this message array.
8: Error condition. The $msg_array parameter determines the location of this message array.

Example of command invocation

FLMCMD SAVE,PROJ1,,USER1,SOURCE,FLM01MD1,,XXX#05,,PASCAL,,,,,CC001234

This service command locks, parses, and stores the information for the member FLM01MD1 of the type SOURCE in the USER1 group. The project name is PROJ1 and the access key is XXX#05. Change code CC001234 is to be added to the information obtained by parsing the member with the PASCAL parser. All other parameters are default values.

Example of call invocation

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

$list_info := NIL;  (* Sets the buffer address to X'00000000' *)

lastrc := FLMLNK('SAVE    ',                  (* service            *)
                  sclm_id,                    (* SCLM ID            *)
                  'USER1   ',                 (* group              *)
                  'SOURCE  ',                 (* type               *)
                  'FLM01MD1',                 (* member             *)
                  'TESTAC  ',                 (* authorization code *)
                  'XXX#05          ',         (* access key         *)
                  '        ',                 (* user ID            *)
                  'PASCAL  ',                 (* language           *)
                  'Y                       ', (* listings           *)
                  'PARSEDD ',                 (* ddname of listings *)
                  'U                       ', (* statistical and dependency info *)
                  'C                       ', (* compilation unit   *)
                  'Y                       ', (* change codes       *)
                  $list_info,                 (* list information pointer *)
                  max_prom_group,             (* maximum promotable group *)
                  $msg_array);                (* message array pointer    *)

This service call locks, parses, and stores the information for member FLM01MD1 of the SOURCE type in the USER1 group. The sclm_id parameter contains a valid SCLM ID returned from the INIT service. The authorization code to be used for the lock verification is TESTAC and the access key is XXX#05. The PASCAL parser parses the member.

SCLM copies parser listings to the PARSEDD ddname only if errors occur. If a parser error does occur, the STORE still completes, SCLM does not draw down compilation units into a different member, and the service verifies all change codes found in $list_info. SCLM returns all messages produced in the $msg_array parameter. You must allocate the PARSEDD ddname before you call FLMLNK.