Standard routines

Each routine has a name divided into 2 parts:

1. The first 5 characters constitute the name of the routine.

For organizational purposes, try to give similar names in alphabetical order (RESA1, RESC2, RESC5) to all the routines that you create for special needs. In this way, they will be easier to find later.

2. The following characters (on 2 to 5 chars.) correspond to the language in which the routine was implemented. It is necessary for each routine to anticipate as much implementation as the language in which it can be used.

All the routines are stored in the source file AARFRTNF1 in the library produced by ARCAD.

The following are the processes that use routines:

1. ACVTPGMFLD Step 3: Automatic modifications of programs. In the case where the routines were configured to be inserted before file writing, or after file reading.
2. ACVTDDSFLD: Automatic modifications of screens and printers. In the case where routines were configured to be inserted before display, or after input.
3. AFMTFLDDTA in *GENPGM: Generation of Recovery programs. You must describe in an RPGLE routine the process model that will allow you to generate recovery programs on the processed PF fields.

The main goal of routines is to simplify jobs. The routine must, therefore, be reliable. For that, first test if the code to be inserted meets the required functionality.

If in doubt, you can build a test (a few programs, screens, files), run the propagation with automatic modifications on your test, apply it, compile, make a few manual modifications and then test the obtained results.

If the testing is satisfactory, you can delete your test in the version using option=99 ; the routine is now ready to be inserted to several copies in a number of sources.

Before devising a routine, it is important to understand its particularity. The points below present scenarios when an RPG, CLP or CBL routine will be in the code to be inserted.

1. RPG, RPGLE

   If an RPG routine is in the code to be inserted (beginning with BEGSR up to ENDSR), it will only be inserted once in the program.

   It is illogical to put the variables $$F1, $$F2, etc.… between a BEGSR and an ENDSR as it will only take the value of these variables.

   Be careful when you visualize the new source (using AWRKFRMCHG and option 8); you may be surprised as the RPG sub-routine will be inserted right in the middle of processing but this gets fixed itself. During the application of modifications, it will be moved to the end of the code.

2. CLP

   In the code to be inserted, you can also include CLP work variable declarations.

   Each one of these variable declarations (beginning with DCL) will only be inserted once in a source (whether it comes from one or several routines); also, the declarations will be in place (after the PGM or the last DCL).

3. CBL

   You can also place COBOL work variable declarations in the code to be inserted.

   Each one of these variable declarations (beginning with a level number (01, 77, ...)) will only be inserted once in a source (whether it comes from one or several routines); also, the declarations will be in place (in the WORKING-STORAGE SECTION).

In this section you will see the list of FRM variables which can be used in standard routines. You can put these variable names either on a code line to be inserted, or on a line in routine check language.

In the source code describing the routines, you can use the following FRM variables; these will be replaced by the name of the true variables at insertion.

$$F1: Name of the actual field in the file (PF, LF or DSPF/PRTF).

$$A1: For the generation of recovery programs, field name in associated file. For a DSPF/PRTF - name of the associated field if it was possible to name it during the propagation process. Otherwise it is blank.

$$F2: For a PF, LF name of the new file field. For a DSPF/PRTF - name of the field added to the screen (*ALWAYS) or newly-renamed field in the screen replacing the previous field (*NEVER).

$$F3: For a PF, LF name of the third file field, if it was defined. For a DSPF/PRTF - name of the “Other” field if you chose to add this other field in the configuration of propagation types (otherwise blank).

$$FM: Original field format. In this format, each character in the field is represented (max. 50 characters).

Be careful of the recovery programs; it is the format of the field as was entered in the LST_CCPLT field for the list of fields to propagate.

The format value is systematically inserted here between two apostrophes, so to test this value in a %IF you must also put the comparison value between two apostrophes.

The following table shows the format value of the field as entered in the LST_CCPLT field.

Field format values

Format Value	Description
$$TY	Type of original field for a character (A, P, S, ...).
$$LG	Total length of the original field. (Ex: 5 or 15)
$$LD	Number of decimals in the original field (Ex: 0 or 2). 0 if it is an alpha field.
$$DF	Original file name (PF, LF, DSPF, PRTF) for the routine insertion.
$$DT	Original file type for the insertion: PF(38), LF.., DSPF.., PRTF..
$$DM	Original file format for the insertion.
$$DP	Code insertion position in relation to the instruction. (A for After, and B for Before)
$$TX	Complete field text (only available for the routines used for generating recovery programs).
$$T1,$$T2,$$T3,$$T4,$$T5	Each one of the 5 parts of the text field, each on 10 characters (from 1 to 10, from 11 to 20, etc. …)

In the entered FRM routines, you can insert check instructions which allow you to direct the insertion processes. These instructions use a mini language based on several commands all starting with % and detailed below.

Once you start using a few lines from this check language, don’t forget to run option 6 = Verify after the routine input. This will avoid incorrect insertions caused by test overlapping such as %IF.

Standard routine languages: here are the language check commands and descriptions:

%CM condition

Commentary - Each line having %CM is a commentary which explains the routine: it will not be inserted in the source; it is ignored by the check language.

%EXIT condition

Insertion end - Once an active line having %EXIT is reached, the insertion stops.

%IF condition

Conditioning the Insertion - After the %IF you can place a test composed of two items to compare separated by a comparison operator; this could be: = > < <> != <= >= LIKE EQ GT LT NE LE GE.

If the condition is verified, the lines placed after the %IF will be inserted into the source; otherwise the insertion will take place after the %ELSE or after the %ENDIF.

If you want to test a value in relation to a blank, enclose the two items with apostrophes: %IF '$$A1’ <> ' '.

In comparison, the two values compared are put as uppercase letters before evaluating the test. (So, ‘Aa’ = ‘AA’ <- Always TRUE.)

For example, the LIKE operator is used with a comparison item in which the points are considered as any character. %IF $$FM LIKE  ‘CCCC....’  indicates that the field format has 8 characters of which the first 4 are Cs and the last 4, any other character.

The conditions can be interlinked (%IF in a %IF, etc..).

%AND condition

Following Conditioning - Allows you to have multiple conditions; the %AND must be placed on the line that follows an %IF, another %AND or an %OR. (%AND has priority over %OR).

%OR condition

Following Conditioning - Allows you to have multiple conditions; the %OR must be placed on the line that follows an %IF, an %AND or another %OR.

%ELSE condition

Negative Conditioning - Indicates the following lines are to be inserted only if the condition placed higher up is not verified.

%ENDIF condition

End of lines to insert for a condition - Indicates the end of a condition started higher up by an %IF. The %IF - %ENDIF must be matched.

%ONCE identifier

Insert once - Indicates that the following lines must be inserted only once in the source (the insertion place will be determined by the type of lines to insert (F, D, I, C Card) in RPG(LE).

After %ONCE, you must specify a 3-character ID that will allow you to clearly identify these lines (in the case where they were already added (for another field), coming from the same or another routine).

Important!

In these lines to be inserted once, do not use replacement variables; only their first value will be taken into account.

%ENDONCE

Indicates the end of a %ONCE block.

Note

If you tend to write complex routines but you cannot anticipate all the cases (only the more frequent), you can arrange for all the non-anticipated cases to show up as compilation errors (therefore requiring manual intervention):

Standard routines are used in two very different cases. These are:

1. Generation of data recovery programs.

2. Insertion of processes after File read or before File write (or update). This action is configured in the propagation type.

   • You indicate by file, either the data files (PF, LF) or the Display/Printer Files (DSPF/PRTF).
   • The insertion is normally carried out just before or just after the order that starts an operation on the file, apart from the odd slight difference.

The AWRKSTDRTN command allows you to manage the standard routines. It displays the list of available routines. You can place yourself on screen from a specific name, and/or select the routines written for a specific language.

In regards to the implementation of a routine for a language, you can enter one of the following options:

Options to implement routines

Option	Description
1 = Select	Allows you to choose the routine (to indicate in the configuration, the propagation types.
2 = Edit	Allows you to modify the routine contents with SEU. If you wish to modify the text, you can do this by exiting SEU then modifying the text and asking for it to be saved.
In COBOL, certain lines may be flagged as being in anomaly under SEU (as you only insert a bit of incomplete code). Also, the variables $$F1 are incorrect in syntax under this name. This will disappear when $$F1 is replaced by the real field name at the insertion into a COBOL source.
3 = Copy	Allows you to copy a routine to a new routine.
4 = Delete	Deletes the routine in the language indicated.
5 = Display	Displays the contents of the routine via SEU.
6 = Check	This option allows you to verify if the FRM syntax for the Routine Check language present in the source is correct or not.

A message will inform you if the command ran successfully i.e. without any errors. If there are errors, a spool file containing the routine with the annotated errors found is displayed.