9.217 TEMPLATE_@@GET_FILS

Note: Built-In Function Rules     Usage Options

From a nominated base file name this facility returns to the caller a list of all related files.

Functionally this Built-In Function acts like the first step of the application template command @@GET_FILS in that from a nominated base file name it returns a list of files.

In a template, the command displays the resulting list to the user for selection. However, the Built-In Function version returns to the list the calling RDML function.

In an application template the user selects files by entering a non-blank value beside them at the workstation. To perform this action from an RDML function use the TEMPLATE_@@SET_FILS Built-In Function.

This Built-In Function can only be used against a function that has been previously placed into an edit session by using the START_FUNCTION_EDIT Built-In Function.

Please Note: This Built-In Function has considerably more power than its online template equivalent @@GET_FILS.

The basic difference is in the ability of this function to extract a much more comprehensive file access route list. The online version prevents the extraction of the same underlying physical file more than once in the complete file list. However this Built-In Functions relaxes this rule so that the same underlying physical file cannot be used more than once in any single access route "chain" or "path" starting from, and including, the base file.

Obviously this limit must be imposed to prevent "closed circuits" or "infinite loops" within the access route "chain" or "path".

It is strongly recommended that any developer who plans to use this function design a simple test function using this Built-In Function to extract and display the resulting file list from a nominated base file. This way the characteristics of this function can be much more easily examined and understood.

Special Note: This Built-In Function provides access to very advanced facilities that basically allow RDML functions to construct new RDML functions.

This is a very specialized area that requires very good knowledge of the LANSA product. Use of this Built-In Function in a "commercial" application (e.g. Order Entry) is not normal and should not be attempted.

This is a Specialized Built-In Function for use in a Development Environment only.

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Name of application template that will be used later via the EXECUTE_TEMPLATE Built-In Function.

1

10

 

 

2

A

Req

Primary or base file name.

1

10

 

 

3

N

Opt

From file number.

Default value is 1.

1

2

 

 

4

N

Opt

To file number.

Default value is 50.

1

2

 

 

5

A

Opt

Physical Files Only.

Must be Y or N.

Default value is Y.

1

1

 

 

6

A

Opt

1:1 Relationships Only.

Must be Y or N.

Default value is Y.

1

1

 

 

 

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Return code

OK = operation completed

ER = fatal error detected

2

2

 

 

2

L

Req

Returned list of related files First entry will be the base file. Working list must have an aggregate length of 40 bytes and is formatted as follows:

From - To   Description

1 - 1   Selection Flag. Format Alpha.
First entry returned as X. Others returned as blanks.

2 - 11   File Name. Format Alpha.

12 - 21   File Library.
Format Alpha.

22 - 22   File Type
P =  Physical
L = Logical.

23 - 32   Underlying Physical File. Format Alpha.
If this file is a physical file then this name will be the same as the entry file name.

33 - 35   Related file entry number. Format Signed, length 3, decimal 0.
1 = the file is directly related to the base file or is the base file.
other = file is indirectly related to the base file via the file specified by this entry number.

36 - 36   Nature of relationship between this file and the related file. Format Alpha.
P = Primary or Base File.
O = One to One
M = Many.

37 - 40   <<Future expansion.>> Format Alpha.

.