WRITEA

Appends a record to a specified file. This function differs from WRITE in that when you initially open a file using the WRITE function, the existing contents of the file are deleted. When you initially open a file with WRITEA, the existing contents are left in place, allowing you to append records to the file.

Note: On mainframe systems, WRITEA only works with sequential datasets. It does not work on PDS datasets.

It is important to note that the distinction between WRITE and WRITEA applies only in the initial opening of the file. Once a file is open WRITE and WRITEA behave in an identical manner. For example, in the following code, the record written by the WRITE function will be appended to the file because the file was initially opened by WRITEA.

WRITEA(%%filename, %%somerecord)
WRITE(%%filename,%%somerecord)

In the example below, the file is opened by the WRITE function. Therefore, the contents of the file are overwritten, regardless of the fact that WRITEA is used afterwards. In this case it would be more appropriate to use WRITE for the second function instead of WRITEA since the file was initially opened with WRITE.

WRITE(%%filename, %%somerecord)
WRITEA(%%filename, %%somerecord)

Note: WRITEA can be used on a line by itself. It does not have to be assigned to a variable.

Syntax

WRITEA(filename,record,[format,length,size])

Arguments


Argument		Description	Default
filename	The name of the file to write to. The data set is only opened once, before processing the first document. Specify * for SYSOUT. You can use the same file in multiple WRITEA calls. Specify `filename` in the same manner for all calls to the same file. filename may be up to 255 characters in length.		None
record	The string to write to `filename`. Each WRITEA call creates a complete record in filename.		None
[format]	The record format of `filename`. `format` is used to:		None
	Open the data set	`format` must match the format of the data set to create or that already exists.
	Write the records	If `format` is fixed, EngageOne™ Enrichment pads the `record` with blanks so that it is `length` characters long
	Valid format options are:
	F	Fixed
	FB	Fixed block
	FBA	Fixed block with ANSI print control.
	FBM	Fixed block with machine print control.
	U	Undefined
	V	Variable
	VB	Variable block.
	VBA	Variable block with ANSI print control.
	VBM	VBM—Variable block with machine print control.
	`format` must match the data set’s record format. If you do not specify format, the data set is opened without specifying a record format. If the data set already exists, the existing setting is used. Otherwise, format U is used. If `format` defaults, the contents of `record` must be valid for the type of data set written. Errors may occur if the data set’s record format is fixed, you allow `format` to default, and you do not write the proper number of bytes in each record. Do not specify `format` if `filename` already exists with record format V or record is the same size as `length`.
[length]	The record length (greater than 0) of `filename`. `length` is used to:		None
	To open the data set	`format` must match the format of the data set to create or that already exists.
	To write the records	If `record` is larger than `length`, truncates `record` prior to writing to filename.
	`length` must match exactly the record length used to create the data set. If you do not specify `length`, EngageOne™ Enrichment opens the data set without specifying a record length. If the data set already exists, EngageOne™ Enrichment opens it using the existing setting. Otherwise, EngageOne™ Enrichment uses length 1024. If you allow `length` to default in this manner, you must ensure that the contents of `record` are valid for the type of data set being written. You should not specify `length` if `filename` already exists and its record format is V or the size of `record` is the same as `length`.
[size]	The block size (greater than 0) of `filename`. `size` is used to open the data set. It must match the format of the data set to create or that already exists. `size` is necessary only if the JCL does not specify a block size. `size` must match the block size used to create the data set. You should not specify `size` if `filename` already exists and its record format is V or the size of `record` is the same as `length`.		None

Results


Result	Description
Return	Null string. If WRITEA is unsuccessful, EngageOne™ Enrichment writes the error message to %%RM.
%%RC	One of the following:
	0	No error.
	1	An error occurred writing to `filename`. EngageOne™ Enrichment did not write the complete record. The return will contain a string detailing how many bytes were written and how many were requested.
	2	An error occurred writing to `filename`. EngageOne™ Enrichment wrote no data. The return contains the mainframe system error message.
	3	Error opening output file.
%%RM	Error message if an error occurred.
%%RV	Always 0.