Using Field Options

Specifying Field Location

START, WIDTH, END, and LENGTH numbers designate the starting and ending columns of a fixed size column of data in a text file. Use START and END when columns are aligned at a fixed column position rather than being separated by specific characters. For example, if the customer ID number (IDNO) is a text field that always begins in column 1 and ends in column 9, specify the following:

IDNO: TYPE TEXT START 01 END 09.

Values can also "float" within a specified column of white space. For example, the field option location description of START 1 WIDTH 9 indicates a value somewhere in the first nine columns of a record. This means that the data in these three records has, in each case, a value of "5".

Column position
123456789
Record 1:  5
Record 2:  5
Record 3:  5

The START @fldname syntax allows you to reset the current (start) position within the input record to redefine an input area for use by other database fields. It allows you to access portions of a field or group of fields. For example:

WholeField: 	TYPE TEXT UNTIL ","
FirstChar:  	TYPE TEXT START @wholeField WIDTH 1

The WholeField is defined as a text field containing all data up to the first comma within the input record. The FirstChar field specification resets the current field position back to the first WholeField position and, since the width is 1, sets the FirstChar field with only the first position of the WholeField value. The LENGTH option can be used in place of WIDTH.

UNTIL describes the character string that is used to delimit or end an input or output text item. A field within a text file is terminated at the first occurrence of the UNTIL string. In the last example, the delimiter is a comma (,), and WholeField continues to the first occurrence of a comma in the record. The specified string can contain escape sequences, such as the following:

\a	Alarm or bell character
\b	Backspace character
\f	Form feed character
\n	New line character
\t	Tab character
\r	Carriage return
\\	Single backslash
\v	Vertical tab character
\0bbb	Octal conversion (where bbb is the octal number to convert to a character)
\0xhh	Hexadecimal conversion (where hh is the hexadecimal number to convert to a character)
\nnn	Integer conversion (where nnn is the decimal number to convert to a character)

UNTIL is useful for fields that are separated by a single word or string. The Connector for Text scans input or output text until it encounters the UNTIL string specification. The Connector for Text scans until the end of the current logical record. However, if it does not find the specified UNTIL string, all data up to the very end of the logical record is placed in the corresponding named field.

UNTIL is useful for describing quoted values separated by commas. For example, the following statement can be delimited by specifying UNTIL "","":

"FIELD 1", "FIELD 2"

Sometimes you want to watch for one of several different individual characters that can indicate the end of a field. The Connector for Text allows you to watch for a list of these individual characters with the UNTILLIST field option. The Connector for Text determines the end of a field at the first occurrence of any individual character in the UNTILLIST string.

UNTILLIST is useful for describing comma-separated values or other data fields separated by a unique character. UNTILLIST can be coded with START, END, and WIDTH parameters, in which case the UNTILLIST string is only searched for within the indicated START, END, or WIDTH columns.

Specifying Formatting Options

The Connector for Text supports the following script options and the functions they represent. Use them by placing the option name at the right side of the field entry.

EBCDIC

EBCDIC to ASCII Conversion

The EBCDIC field option converts input fields from EBCDIC to ASCII before adding the fields to a Notes® document.

Example: In this example, Connector for Text reads EBCDIC data from a tape dump and converts it to HEI text.

;EBCDIC.ZID
Type: TYPE TEXT VALUE "Stock"
Part: TYPE TEXT START 1 WIDTH 12 EBCDIC
Quantity: TYPE TEXT START 13 WIDTH 3 EBCDIC
Description: TYPE TEXT START 16 WIDTH 24 EBCDIC

FORMAT

Use this to set date format or special field format.

FORMAT specifies the format for an input or output field. The field can be one of several types: DATE, TEXT, or NUMBER. This section describes the use of the FORMAT field option with each type.

FORMAT with TYPE DATE

Use the format_spec for DATE fields to identify the various components of a date and/or time field where, for dates:

M designates a month field

N designates a month name (for example, January, Feb, April). A month name must be at least three characters long to guarantee uniqueness.

D designates a day field

Y designates a year field. A lower case 'y' indicates a two-digit 20th century year. The Connector for Text adds 1900 to the year value.

J indicates a Julian date

W designates a weekday name (for example, Monday). This is used in output only and for times:

h designates an hour field

m designates a minutes field

s designates a seconds field.

A or P indicates use of a meridian indicator (AM or PM). For example, if a date field had the following form:

02xxxMAR0315

the ZID entry could be (unrecognized characters are disregarded, so that "x" is disregarded):

Important Date: TYPE DATE BEGIN 1 WIDTH 12 FORMAT "YYxxxxxxMMDD"

This would transform the ImportantDate field to a date with the format, "03/15/02."

FORMAT with TYPE TEXT or NUMBER

Use the format_spec to conditionally change values from the actual input values. The syntax for conditional FORMAT specifications is:

FORMAT "a,b,c=X;d,e=Y;Z"

You can read the format specification as:

IF the input field is equal to a, b, or c, then set value to X

ELSE if the input field is equal to d or e, then set value to Y

ELSE set value to Z

If a final ELSE clause (without compare values) is not given, then the input value is unchanged.

Example:

This example uses a variety of date and text formats for an employee record.

; Mon_Name2 ZID SCRIPT
;
Type: TYPE TEXT VALUE "Employees"
Name: TYPE TEXT UNTIL ","
HireDate: TYPE DATE FORMAT NNN-DD-YY UNTIL ","
Title: TYPE TEXT FORMAT "Pres,Pre=CEO,Man,Mgr=MGR,EMP" UNTIL ","
Date_Of_Birth: TYPE DATE FORMAT yy-MMDD  UNTIL \r\n
*
Claude Hopper,Mar-07-95,Pres,14-0904
Evander Holyfield,Jun-30-96,Man,69-0315

RIGHT

Use this to right-justify output.

With output TEXT data, you can control whether the data is left or right justified. The default justification is left. To override this and make it right justification, you must do two things:

• Specify the LENGTH of the data on the output field.
• Specify RIGHT on the output field.

Example:

In this example, the Connector for Text sets the length of CompanyName, the field to be output, to 40 and specifies right justification. This results in leading white space for company names of less then 40 characters in length.

; RIGHT ZID SCRIPT
;Type: TYPE TEXT VALUE "1. Customer Profile"
CompanyName:    	TYPE TEXT  UNTIL \r\n LENGTH 40 RIGHT
CompanyAddress: 	TYPE TEXT  UNTIL \r\n
CompanyCity:    	TYPE TEXT  UNTIL \r\n
CompanyState:   	TYPE TEXT  UNTIL \r\n
CompanyZip:     	TYPE TEXT  UNTIL \r\n
CompanyPhone:   	TYPE TEXT  UNTIL \r\n
CompanyFax:    	TYPE TEXT  UNTIL \r\n
Body:           	TYPE RICH UNTIL \r\n  SEP \r\n

SEPARATOR

Use this to enable a multiple-value list delimiter.

For non-rich text fields, SEPARATOR or "SEP" describes the characters separating multiple-value list items. SEP is useful for describing Notes® multiple-value "list-type" fields whose elements are separated by a unique character. Other database types might or might not support multivalue list types.

For rich text fields, Connector for Text creates new rich text lines at each occurrence of the SEPARATOR string. For example: If your separator string is "$$", you would enter "$$". The default line separator is carriage-return and line feed characters, or "\r\n". When the default is used, any combination of carriage-return and line feed characters creates a new line.

Escape sequences are allowed as follows:

\a	alarm or bell character
\b	backspace character
\f	form feed character
\n	new line character
\r	carriage return character
\t	tab character
\v	vertical tab character
\0bbb	octal conversion (where bbb is the octal number to convert)
\0xhh	hexadecimal conversion (where hh is the hexadecimal number to convert)
\nnn	integer conversion (where nnn is the decimal number to convert)

Example:

In this example, Connector for Text defines the SEP character string as "#," overriding the defaults of carriage return and line feed.

; NSEP ZID SCRIPT
Type: 	TYPE TEXT VALUE "Letter"
Subject:	TYPE TEXT UNTIL "," VIEWKEY 1
Author: 	TYPE TEXT UNTIL ","
Body:	TYPE TEXT SEP "#" UNTIL \0x0c\r\n
*
Painters Invade Monhegan Island, SWD, LINE1#LINE2#LINE3#LINE4

TRIM

Use this to eliminate extra white space in your input data. When the TRIM field option is used, Connector for Text removes leading, trailing, and multiple interspersed white space characters (blanks and tabs).

Example:

In this example, input data embedded in the ZID script has extra white space in it. Using the TRIM field option, Connector for Text parses out the white space.

; TRIM ZID
Type: 		type text value "Stock"
Part:    	TYPE TEXT UNTIL "," viewkey 1 TRIM
Quantity:	TYPE TEXT UNTIL "\n"
*
Rubber      Hoses		,125
Widgets and        Gidgets	  ,255

The output will look like this:

Rubber Hoses, 125
Widgets and Gidgets, 255

VALUE

Use this to set default values for input fields.

The value_spec is the default value for an input field. This is useful for adding new fields to a Notes® document that have no corresponding input field. For example, given the ZID descriptor:

OFFICE_TITLE: TYPE TEXT VALUE "Originator"

Every document that the Connector for Text adds to or updates from input would be given a new field, named OFFICE_TITLE, with a value of "Originator."