9 200 START_FILE

You are here:

9.200 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

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

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.

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)