9.203 START_FILE_EDIT

Note: Built-In Function Rules     Usage Options

Starts an "edit session" on the definition of a nominated LANSA file definition.

The edit session can be used to define a new file or alter an existing one.

The file definition is locked for exclusive use throughout the edit session.

Only one file definition can be edited at one time (ie: it is not possible to concurrently edit 2 file definitions from within the same job).

Details of the new or amended file definition will be lost unless the END_FILE_EDIT Built-In Function is used to "commit" them.

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 file to be edited

1

10

 

 

2

A

Req

Library in which file resides

*LIBL or *FIRST is acceptable when editing an existing file definition.

*DEFAULT is acceptable when editing an existing file definition or creating a new one.

Note: When coding *FIRST, *DEFAULT, *LIBL,etc., they must be placed in extra quotes to distinguish them as literals and not system variables. Thus, three single quotes must be coded round the argument. e.g. '''*FIRST'''.
It is NOT valid to code double quotes and single quotes ("'*FIRST'")
Refer to the Example.

1

10

 

 

3 **

A

Req

Source of edited details. Must not be blank, LAN or OTH.

3

3

 

 

4

A

Opt

File description Must not be blank. Required for a new file.

1

40

 

 

5

A

Opt

Initial public access. Required for a new file. ALL, NORMAL or NONE allowed.

1

6

 

 

6

A

Opt

File component edit options

Byte 1: Y or N indicates that fields are to be edited. Default value is Y.

Byte 2: Y or N indicates that logical views/files are to be edited. Default value is Y.

Byte 3: Y or N indicates that access route details are to be edited. Default value is Y.

When a byte is passed as N, the associated component of the file definition remains unchanged during the edit session and is not flagged for pending deletion as described below. Any attempt to edit that component of the file definition will cause a fatal error.

3

3

 

 

 

** The "source" of the edited details is vital. When an edit session is commenced all details of the file definition that have the same "source" as that passed to the START_FILE_EDIT Built-In Function are flagged for pending deletion. If the details are not "re-specified" by one of the FILE_FIELD, LOGICAL_VIEW, etc Built-In Functions, they are deleted from the file definition by the END_FILE_EDIT Built-In Function. The exception is those that have been specifically excluded from editing using one or more of the byte positions in the 6th argument previously described. This allows for file details specified by other sources (such as direct input via the LANSA Review or change a file definition facility in the The File Control Menu) to remain intact during a file edit session.

Examples of this "source" code would be:

LDM

LANSA data modeling interface

IEW

Information engineering workbench interface

ACC

Accelerate data modeling interface

Once set, the source code used should never be changed within a particular type of interface.

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Return code

OK = edit session commenced

ER = fatal error detected

In case of "ER" return code error message(s) are issued automatically and the edit session ended without commitment.

2

2

 

 

 

Example

The following example defines all details of a simple name and address file called NAMES to the LANSA system by using Built-In Functions rather than the conventional menu driven interfaces.

*** Define the fields into the data dictionary (no prompting)

*

USE     BUILTIN(PUT_FIELD) WITH_ARGS('N' 'CUSTNO' 'S' 007 0 ' ' 

        'Customer number') TO_GET(#RETCODE)

USE     BUILTIN(PUT_FIELD) WITH_ARGS('N' 'CUSNAME' 'A' 010 0 ' ' 

        'Customer name') TO_GET(#RETCODE)

USE     BUILTIN(PUT_FIELD) WITH_ARGS('N' 'ADDRESS1' 'A' 020 0 ' ' 

        'Address line 1') TO_GET(#RETCODE)

USE     BUILTIN(PUT_FIELD) WITH_ARGS('N' 'ADDRESS2' 'A' 020 0 ' ' 

        'Address line 2') TO_GET(#RETCODE)

USE     BUILTIN(PUT_FIELD)WITH_ARGS('N' 'ZIPCODE' 'S' 006 0 ' ' 

        'Zip code') TO_GET(#RETCODE)

*

*** Start an edit session on the new file NAMES in library QGPL

*

USE     BUILTIN(START_FILE_EDIT) WITH_ARGS('NAMES' 'QGPL' 'DEM'

           'Customer details' 'NORMAL') TO_GET(#RETCODE)

*

*** Use of triple quotes round *FIRST and *DEFAULT libraries

*

USE     BUILTIN(START_FILE_EDIT) WITH_ARGS('CODES' '''*FIRST''' 'TST' 'Codes details' 'NORMAL') TO_GET(#RETCODE)

*

USE     BUILTIN(START_FILE_EDIT) WITH_ARGS('SALES' '''*DEFAULT''' 'PRD' 'Sales results' 'NORMAL') TO_GET(#RETCODE)

*

*** Define the fields in the file

USE     BUILTIN(FILE_FIELD) WITH_ARGS('CUSTNO') TO_GET(#RETCODE)

USE     BUILTIN(FILE_FIELD) WITH_ARGS('CUSNAME') TO_GET(#RETCODE)

USE     BUILTIN(FILE_FIELD) WITH_ARGS('ADDRESS1') TO_GET(#RETCODE)

USE     BUILTIN(FILE_FIELD) WITH_ARGS('ADDRESS2') TO_GET(#RETCODE)

USE     BUILTIN(FILE_FIELD) WITH_ARGS('ZIPCODE') TO_GET(#RETCODE)

*** Define the primary or relational file key

*

USE     BUILTIN(PHYSICAL_KEY) WITH_ARGS('CUSTNO') TO_GET(#RETCODE)

*

*** Define additional logical view in CUSNAME / ZIPCODE order

USE     BUILTIN(LOGICAL_VIEW) WITH_ARGS('NAMESV1' 'Customers in name order') TO_GET(#RETCODE)

*

*** Define keys of logical view NAMESV1

USE     BUILTIN(LOGICAL_KEY) WITH_ARGS('NAMESV1' 'CUSNAME') TO_GET(#RETCODE)

USE     BUILTIN(LOGICAL_KEY) WITH_ARGS('NAMESV1' 'ZIPCODE') TO_GET(#RETCODE)

 

*** Define "one to one" access route to ZIPTABLE by using key ZIPCODE

USE     BUILTIN(ACCESS_RTE) WITH_ARGS('DEM1' 'Zip details' 'ZIPTABLE' '''*FIRST''' 1 'N/AVAIL') TO_GET(#RETCODE)

USE     BUILTIN(ACCESS_RTE_KEY) WITH_ARGS('DEM1' 'ZIPCODE') TO_GET(#RETCODE)

*

*** Define "one to many" access route to ORDHDRV2 using key CUSTNO

USE     BUILTIN(ACCESS_RTE) WITH_ARGS('DEM2' 'Order details' 'ORDHDRV2' '''*FIRST''' 999 'IGNORE') TO_GET(#RETCODE)

USE     BUILTIN(ACCESS_RTE_KEY) WITH_ARGS('DEM2' 'CUSTNO') TO_GET(#RETCODE)

*

*** End the edit session and commit details

USE     BUILTIN(END_FILE_EDIT) WITH_ARGS('Y') TO_GET(#RETCODE)