CometWiki - User contributions [en]

Mnemonics "E"

2026-01-26T22:53:25Z

Justin:

==(Easy Scan)==

'''Mnemonic''': (Easy Scan) Hex equivalent: "@0E0000@"

'''Discussion''': The (Easy Scan) mnemonic places the Comet console into "easy scan" mode.<br>
(This mnemonic does not apply to QTerm or terminals.) <br>
In "easy scan" mode, if the user presses one of the recognized keys while the program is at an INPUT prompt, the program responds as if an F10, Enter, or Tab key was pressed.<br>
In combination with the returned screen coordinates (see INPUT), this feature allows for an enriched style of screen I/O programming.

In addition, if the mouse driver is active (see the (Mouse On) mnemonic), a mouse click also generates a transmit, and places the cursor's coordinates in the status buffer (see Example 2).<br>
Starting with Comet98 Build 232, (Easy Scan) turns the mouse on if it is not already being done.

The (Scan Codes Off) mnemonic terminates "easy scan" mode.

The "reason for transmit" information is stored in the 8th byte of the console's status buffer, and is stored in hex.<br>
To determine which key (or click) caused the transmit to occur, perform the following operation:

VALUE = ASC(SUB(STS(0),8,1))

'''Note:''' VALUE is a numeric field with length/precision of 3.0.

The following values are returned:

Value Key that caused the transmit to occur
*4 Up arrow
*5 Down arrow
*6 Left mouse click
*7 Ctrl + Home
*8 Ctrl + End
*9 Pg Up
*10 Ctrl + Pg Up
*11 Pg Dn
*12 Ctrl + Pg Dn
*14 Right mouse click
*15 Window caption bar "X" was clicked. '''See''' (CreateWindowEx).
*16 ?
*17 X1 mouse click (usually side 'back' button)
*18 X2 mouse click (usually side 'forward' button)
*19 Mouse wheel scroll 'back'
*20 Mouse wheel scroll 'forward'

Values 1, 2, and 3 are generated via the INPUT statement, and do not require the (Easy Scan) mnemonic.

'''History:''' The (Easy Scan) mnemonic was added in Comet version 504.208 as part of the enhanced INPUT statement. <br>
Values 7 through 12 were added in Comet 504.228 and Comet98 Build 228.

Starting with Comet98 Build 232, (EasyScan) turns the mouse on if it is not already being done. <br>
If it is already on, it is assumed the whoever turned it on will also turn it off.

Starting with Build 292, (EasyScan) disables any scan modes that are currently enabled.

Value 14 was added in Build 294.

As of Build 294, (EasyScan) mouse clicks now occur on the up-click instead of the down-click.<br>
This is consistent with other Windows applications.

Value 15 was added in Comet2002 Build 306.

Values 17-20 were added in Comet 542.

Example 1:
PRINT (0) (Mouse On) ! Mouse on (optional)
.
PRINT (0) (Easy Scan) ! Easy scan mode on
.
.
INPUT (0) DATA$ ! Input a field
.
VALUE = ASC(SUB(STS(0),8,1)) ! Reason for transmit
.
IF VALUE = 1 ... ! F10 key
IF VALUE = 2 ... ! Enter key
IF VALUE = 3 ... ! Tab key
IF VALUE = 4 ... ! Up arrow
IF VALUE = 5 ... ! Down arrow
IF VALUE = 6 ... ! Left mouse click
IF VALUE = 7 ... ! Ctrl + Home
IF VALUE = 8 ... ! Ctrl + End
IF VALUE = 9 ... ! Pg Up
IF VALUE = 10 ... ! Ctrl + Pg Up
IF VALUE = 11 ... ! Pg Dn
IF VALUE = 12 ... ! Ctrl + Pg Dn
IF VALUE = 14 ... ! Right mouse click
IF VALUE = 15 ... ! Window caption bar "X"
IF VALUE = 17 ... ! X1 mouse click (usually side 'back' button)
IF VALUE = 18 ... ! X2 mouse click (usually side 'forward' button)
IF VALUE = 19 ... ! Mouse wheel scroll 'back'
IF VALUE = 20 ... ! Mouse wheel scroll 'forward'
.
.
.
PRINT (0) (ScanCodesOff) ! Easy scan mode off
PRINT (0) (Mouse Off) ! Mouse off (optional)

'''Example 2:'''
Data$ = Sub(Sts(0), 1, 254) ! Get console status
J = Asc(Sub(Data$, 8, 1)) ! Get reason for transmit
If (J EQ 6) ! Mouse was clicked
Row = Asc(Sub(Data$, 15, 1)) ! Get the row
Col = Asc(sub(Data$, 16, 1)) ! Get the column
Endif

This example shows how to determine the cursor's coordinates when the mouse is clicked.

==(Ellipse)==
'''Mnemonic''': (Ellipse=left, top, right, bottom)

'''Discussion''': This mnemonic draws an ellipse.
The center of the ellipse is the center of the bounding rectangle specified by left, top, right, bottom. <br>
The ellipse is drawn with the current pen, and its interior is filled with the current brush.<br>
The figure drawn by this function extends up to, but does not include, the right and bottom coordinates.<br>
This means that the height of the figure is bottom - top and the width of the figure is right - left.<br>

If either the width or the height of the bounding rectangle is 0, no ellipse is drawn.

'''History:''' This mnemonic is valid in Comet98 and greater

== (EmailDocument) ==
'''Email Mnemonic:''' (EmailDocument=string-argument)

'''Discussion:''' The (EmailDocument) mnemonic may be used to specify the name associated with an attachment file. If an extension is not assigned, one appropriate for the file type will automatically be included (.pdf, .htm, etc). If this mnemonic is not used, the attachment will carry the default name assigned to the document.
<pre>
Example:
OPEN (1) "LEH"
PRINT (1) (EmailDocument="OrderDetails")
</pre>

== Email printer mnemonics ==

{| border="1"
|Mnemonic
| Description
|-
|(Server = SMTPServerName$)
| Specify SMTP server name and port
|-
|(Domain = Domain$)
|Specify email domain name
|-
|(From = FromAddr$)
| Specify sender's name and address
|-
|(To = ToAddr$)
|Specify recipient's name and address
|-
|(CC = CCaddr$)
|Specify CC recipient's name and address
|-
|(BCC = BCCaddr$)
|Specify BCC recipient's name and address
|-
|(Subject = Subject$)
|Specify message's subject line
|-
|(Text = Text$)
|Specify a line of body text
|-
|(EmailDocument = Name$)
| Specify a name for the attachment
|-
|(Log = LogFile$,LogDir$,ERASE)
|Specify a log file name and erase parameter
|-
|}
Discussion of the Email Printer (requires access to web site)

Read about other Email Mnemonics

== (EN) ==

'''Mnemonic:''' (EN)

'''Hex equivalent:''' "@0E06@"

'''Discussion:''' Enter normal mode.<br>
The (EN) control code sets the video display in normal mode.<br>
The location of displayed information, the placement of the cursor, and the places where data is transmitted are determined by the FORMAT statements in the program.

The alternative to normal mode is typewriter mode.

'''Example: a'''.
100 FORMAT (EN);(SB);"CUSTOMER INQUIRY",@(10,0)
.
PRINT (0,100)

'''Example b.'''
PRINT (0) (EN);(SB);"CUSTOMER INQUIRY",@(10,0)

This example shows how to set normal mode, either at the beginning of a FORMAT statement or within a PRINT statement. <br>
The additional controls set background mode and display a heading at column 10, row 0.

== (Enable Close) ==

'''Mnemonic:''' (EnableClose = Arg)

Where:

Arg = 0 – Disable [X] on main view window (If [X] is clicked the message: "Close has been disabled by the currently running program" will be displayed)

Arg = 1 – Enable [X] on main view window if disable count reaches 0 (see discussion below)

Arg = <anyothervalue> – Reset count and enable [X] on main view window

'''Discussion''': Enables or disables the [X] close button at the top of a main Comet Window. Due to the possibility of nested programs calling this mnemonic, Comet will maintain a count of the number of “disables” issued. Only when the disable count reaches 0 will the close button be enabled. If a value other than 0 or 1 is issued then the disable count will be forced to 0 and the close button will be enabled. This mnemonic requires at minimum Comet build 451 and REL version 11.10.

'''Example:'''
Print (EnableClose = 0) ! Disable [X] button while processing
.
. ! Perform uninterrupted processing
.
Print (EnableClose = 1) ! Done - Enable [X] button

== (End Metafile) ==

'''Mnemonic:''' (EndMetafile = flags)

'''Discussion''': End the metafile collection process by saving and/or executing the currently active MetaFile.

Where flags indicate:

VMF.SAVE = 0 ! Save the file - do not execute<br>
VMF.EXECUTE = 1 ! Execute the metafile

== (EndWaitCursor) ==

'''Mnemonic''': (EndWaitCursor)

'''Discussion:''' This mnemonic turns off the hourglass cursor.

'''See''' (BeginWaitCursor) and (RestoreWaitCursor).

'''Example:'''
Print (BeginWaitCursor)
.
.
.
Print (EndWaitCursor)

== (Enhanced Mouse On) ==

'''Mnemonic:''' (Enhanced Mouse On)

'''Hex equivalent:''' "@0E0906@"

'''Discussion:''' This control opens the enhanced mouse driver (if possible).

'''Also see''' (BIOS Mouse On) and (Mouse On).

'''Example: a.'''
100 FORMAT (Enhanced Mouse On)
.
PRINT (0,100)

'''Example b'''
PRINT (0) (Enhanced Mouse On

==[[Enhanced Printing]]==

Link to Enhanced Printing Summary

== (ET) ==

'''Mnemonic:''' (ET)

'''Hex equivalent:''' "@0E05@"

'''Discussion:''' Enter typewriter mode. <br>
The (ET) control code sets the video display in typewriter mode.<br>
Each new line of data written to the screen causes the screen to scroll up one line. <br>
The new line of data is written on the bottom line of the screen in background mode.

Transmit marks are automatically placed after the last byte of data written and at the lower right corner of the screen (making the remaining part of the bottom line the foreground data entry field).

The cursor is placed at the left-most position of the foreground field on the bottom line.

The alternative to typewriter mode is normal mode.

'''Example: a.'''
100 FORMAT (ET)
.
PRINT (0,100)
PRINT (0) "ENTER CUSTOMER NUMBER:"
INPUT (0) CUSTNUM$

'''Example b.'''
PRINT (0) (ET)
PRINT (0) "ENTER CUSTOMER NUMBER:"
INPUT (0) CUSTNUM$

In this example, the screen is placed into typewriter mode. <br>
Then a prompt is displayed and data is accepted into the variable named CUSTNUM$. <br>
Items such as foreground, background and transmit marks are handled automatically.

== (EraseFile) ==

'''Mnemonic:''' (EraseFile=file,flags)

'''Discussion:''' The mnemonic erases a Windows file.

This mnemonic may be used by foreground programs only.

The file name is in Windows format, UNC format, or a directory alias.

Flags is the sum of the specified decimal values from the following chart:

{| Border=1
|Flag
|Description
|-
|0
|Perform function on the server, CometAnywhere or not.
|-
|1
|Perform function on the client, CometAnywhere or not.
|-
|2
|Perform function for CometAnywhere only and perform it on the client.
|-
|}

After this mnemonic is issued, your program can issue an INPUT on LUN (0) to retrieve the error information.

'''For example:'''

LENGTH 2 & LOCAL AX$,DX$
LENGTH 254 & LOCAL RESULT$
ResultFmt: FORMAT AX$;DX$;RESULT$
.
.
Print (EraseFile=File$,Flags)
Input (0,ResultFmt)
.
The first field, AX$, contains the function error code, and the second field, DX$, contains the suberror code (aka the Windows file error code).
Both of these fields are in Intel 2's complement format, and should be processed as follows:
AX$ = SUB(AX$,2,1) + SUB(AX$,1,1) ! Flip the bytes around
DX$ = SUB(DX$,2,1) + SUB(DX$,1,1) ! Flip the bytes around
FuncError = HexDec(AX$) ! Function error code (decimal)
FileError = HexDec(DX$) ! File error code (decimal)
.
! For unexpected values, convert to 2's complement signed integer
If (FuncError > 32767) FuncError = FuncError-65536
If (FileError > 32767) FileError = FileError-65536

Here is a list of the function error codes in decimal form:

'''Error'''
{| Border=1
|(FuncError)
| Description
|-
|0
| Function not supported
|-
|1
| Success
|-
|2
| CometAnywhere required
|-
|3
| Source file error (see suberrors)
|4
|Aborted by user
|-
|5
| Function in progress
|-
|}

Here is a list of the suberror codes (common Windows file errors) in decimal form:

'''Suberror'''
{| Border=1
|(FileError)
| Description
|-
|0
| Success
|-
|2
| File not found
|-
|3
| Path not found
|-
|5
|Access denied
|-
|12
|Invalid access
|-
|15
|Invalid drive
|-
|16
|An error has occurred in the current directory
|-
|18
|No more files
|-
|32
|Sharing violation
|-
|33
|Lock violation
|-
|80
|File exists
|-
|161
|Bad pathname
|-
|}
'''History:''' This mnemonic was added in Comet Build 299 and REL Version 01.07.

== Execute Metafile ==

'''Mnemonic:''' (ExecuteMetafile = FileName)

'''Discussion:''' Executes the previously saved metafile FileName.

New Winsock Gateway Control - CERT-VALIDATION

2025-03-29T01:26:03Z

Justin:

== New Winsock Gateway (TCP Device) Control - CERT-VALIDATION ==

As of Comet release 540, a new '''CERT-VALIDATION''' control has been added to the Winsock gateway (TCP Device) for managing SSL certificate verification. This control determines how the gateway handles certificates from the host.

=== Usage ===

'''CERT-VALIDATION''', like '''SSL-ENABLE''', must be set before connecting to the remote server.

==== Syntax ====

result$ = control(LUN, "CERT-VALIDATION value")

Options:

*'''VERIFY'''
*'''VERIFY-AND-ASK''' (default)
*'''DONOT-VERIFY'''

If not specified, or the control is not issued, the default behavior is '''VERIFY-AND-ASK'''.

==== Options ====

VERIFY

Ensures the certificate is valid before connecting. The connection will fail if verification fails, preventing connections with invalid or broken certificates (recommended for security).

VERIFY-AND-ASK (Default)

Attempts verification and prompts the user if the certificate is invalid. This was the only behavior before Comet 540 and requires user confirmation before proceeding.

DONOT-VERIFY

Skips verification, allowing connections even with invalid certificates. Useful for testing but not recommended for security reasons.

=== Example ===

For example, this code enables the SSL protocol, specifies that we will only accept valid certificates, then connects to the server:

open(LUN) "TCP" excp=tcperror

result$ = control(LUN, "SSL-ENABLE")
print "<<"; result$

result$ = control(LUN, "CERT-VALIDATION VERIFY")
print "<<"; result$

result$ = control(LUN, "CONNECT example.com 443", excp=tcperror)

New Winsock Gateway Control - CERT-VALIDATION

2025-03-16T00:49:23Z

Justin:

== New Winsock Gateway (TCP Device) Control - CERT-VALIDATION ==

As of Comet release 540, a new '''CERT-VALIDATION''' control has been added to the Winsock gateway (TCP Device) for managing SSL certificate verification. This control determines how the gateway handles certificates from the host.

=== Usage ===

'''CERT-VALIDATION''', like '''SSL-ENABLE''', must be set before connecting to the remote server.

==== Syntax ====

result$ = control(LUN, "CERT-VALIDATION value")

Options:

*'''VERIFY'''
*'''VERIFY-AND-ASK''' (default)
*'''DONOT-VERIFY'''

If not specified, or the control is not issued, the default behavior is '''VERIFY-AND-ASK'''.

==== Options ====

VERIFY

Ensures the certificate is valid before connecting. The connection will fail if verification fails, preventing connections with invalid or broken certificates (recommended for security).

VERIFY-AND-ASK (Default)

Attempts verification and prompts the user if the certificate is invalid. This was the only behavior before Comet 540 and requires user confirmation before proceeding.

DONOT-VERIFY

Skips verification, allowing connections even with invalid certificates. Useful for testing but not recommended for security reasons.

=== Example ===

For example, this code enables the SSL protocol, specifies that we will only accept valid certificates, then connects to the server:

open(LUN) "TCP" excp=tcperror

result$ = control(LUN, "SSL-ENABLE")
print "<<"; strip(result$)

result$ = control(LUN, "CERT-VALIDATION VERIFY")
print "<<"; strip(result$)

result$ = control(LUN, "CONNECT example.com 443", excp=tcperror)

New Winsock Gateway Control - CERT-VALIDATION

2025-03-16T00:43:23Z

Justin: Created page with "== New Winsock Gateway (TCP Device) Control - CERT-VALIDATION == A new CERT-VALIDATION control has been added to the winsock gateway (TCP Device) for managing SSL certificate ve..."

== New Winsock Gateway (TCP Device) Control - CERT-VALIDATION ==

A new CERT-VALIDATION control has been added to the winsock gateway (TCP Device) for managing SSL certificate verification on the host side. Using this new control, you can tell the winsock gateway how to behave based on the certificate received from the host.

=== Usage ===

This control, like the SSL-ENABLE control, must be issued prior to connecting to the remote server. The syntax is as follows:

result$ = control(LUN, "CERT-VALIDATION value")

Where value can be one of three options:

VERIFY
VERIFY-AND-ASK (default)
DONOT-VERIFY

If the CERT-VALIDATION control is not specified, the default behavior is VERIFY-AND-ASK.

=== Options ===

==== VERIFY ====

VERIFY

This option ensures the certificate is valid before connecting. The connection will fail if verification fails. This is the recommended setting for security, as the connection will not be allowed for invalid or broken certificates.

==== VERIFY-AND-ASK ====

VERIFY-AND-ASK

This is the default option, and was the only behavior prior to Comet release 540.

Attempts verification and if there is an issue (invalid or broken certificate) Comet will pop up a message box asking the user if they wan to trust the certificate. This option is good to ensure the user is aware if the certificate is invalid, but requires user interaction for the XAP program to continue.

==== DONOT-VERIFY ====

DONOT-VERIFY

Skips verification and allows connections even with invalid certificates. This option can be useful for testing with invalid or broken certificates, but is not recommended for security reasons.

Main Page

2025-03-16T00:25:14Z

Justin:

='''Comet by Signature Systems, Inc.'''=

* [[Getting Started With Comet]]

* [[Subscription Benefits]]

* [[Virtual Dongle]]

* [[FAQs]]

* [[CFILES - the replacement for DbMgr]]

* [[Comet Meetings]]

* [[Configuration and Installation]]

* [[Programming]]

* [[Comet32]]

* [[STL Containers]]

* [[Xap and Comet32]]

* [[Products]]

* [[Utilities]]

* [[Comet Tips]]

* [http://support.signature.net/ Support - Users Forum]

* [[How to edit this Wiki]]

* '''[http://cc.signature.net/guest/adduser Request ability to edit pages on this Wiki]'''

*[[Comet And RDP]]

* [[New XAP controls and File Upload]]

* [[New Winsock Gateway Control - CERT-VALIDATION]]

A hint from the old guy. The Wiki's text size is based on the browser's settings. In '''Firefox''' I set the minimum font size to 16.

Tools >> Options >> Content >> Advanced. Minimum font size.

New XAP controls and File Upload

2025-03-14T18:36:31Z

Justin:

== New XAP Controls and File Upload ==

=== New Controls ===

As of Comet version 540, we have introduced new controls to enhance XAP’s support for form input arrays and file uploads. These controls are designed to improve data handling while maintaining backward compatibility. If you do not enable these new features, your existing programs will continue to function as they did in previous XAP versions, ensuring a seamless transition.

----

==== WRITEEMPTYFIELDS (#XAP Setting) ====

Force XAP to write keys to the CGIFILE even if the value is empty.

By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have

<input type="text" name="stringinput" />

and the form is submitted with no text in the input field, then XAP will NOT write '''Q.STRINGINPUT''' into the CGIFILE.

By including

WRITEEMPTYFIELDS TRUE

into your #XAP file, even if the value in the text input is empty, there will be a '''Q.STRINGINPUT''' key in the CGIFILE, with a blank record for the value.

----

==== URLDECODEKEYS (#XAP Setting) ====

Tell XAP to decode special characters when writing the keys in the CGIFILE.

By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.

So if we have a input field for text named like this:

<input type="text" name="stringinput[]" />

XAP will write the key for this input field into the CGIFILE as '''Q.STRINGINPUT%5B%5D'''

By including

URLDECODEKEYS TRUE

into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''

----

==== GET FILEDATA (XAP Control) ====

Retrieve the data from an uploaded file inside an XAP program.

When a file is uploaded to XAP using the '''type="file"''' input attribute, the name is stored in the CGIFILE. For example:

<input type="file" name="myFile">

will display an HTML input element to upload a file. When a file is specified and submitted, the CGIFILE will contain:

Q.MYFILE - filename.ext

In order to retrieve the data from the upload, use the '''GET FILEDATA''' control to copy the file into a dynamic string:

filedata$ = control(0, "GET FILEDATA filename.ext")

From here you can use something like '''PRINTFILE''' to save the data to the filesystem.

Note, this method copies the entire file as a chunk of data into a dynamic string. Be aware that large files could cause performance issues depending on usage.

----

=== Array Handling for Form Elements ===

==== Overview ====

XAP now supports HTML form input arrays. This allows multiple values to be submitted under the same field name and stored in an indexed array. This functionality enhances data collection and processing for forms.

==== Defining an Input Array ====

To designate an input field as an array, append '''[]''' to its '''name''' attribute. Each value submitted will be stored as a zero-indexed array using the input name as the key.

Example:

<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">

This example creates four text input fields in an HTML form.

==== How XAP Handles Input Arrays ====

When submitted, the data will be stored in the CGIFILE with key/value pairs in the order they appear:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - second value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

The last key, '''Q.STRINGINPUT[]''', ensures backward compatibility with older XAP versions where only the last submitted value was stored.

==== URL Decoding of Keys ====

If '''URLDECODEKEYS TRUE''' is included in the #XAP file, the query keys will be properly decoded. Without this setting, the CGIFILE will store encoded keys:

Q.STRINGINPUT%5B0%5D - first value
Q.STRINGINPUT%5B1%5D - second value
Q.STRINGINPUT%5B2%5D - third value
Q.STRINGINPUT%5B3%5D - fourth value
Q.STRINGINPUT%5B%5D - fourth/last value

==== Handling Empty Values ====

By default, XAP does not write key/value pairs to CGIFILE if the field is left empty. For example, if the second input field is empty, the stored values would be:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

To force XAP to store all fields, including empty ones, use the '''WRITEEMPTYFIELDS TRUE''' setting. This ensures all key/value pairs are written:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - empty
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

==== Summary ====

*Use '''name="fieldname[]"''' in your '''<input>''' element to create input arrays.

*XAP stores submitted values as zero-indexed arrays.

*The last submitted value is also stored under '''Q.FIELDNAME[]''' for backward compatibility.

*Use '''URLDECODEKEYS TRUE''' to properly decode keys.

*By default, empty values are not stored; enable '''WRITEEMPTYFIELDS TRUE''' to include them.

----

=== New XAP File Upload Mechanics ===

==== Overview ====

XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.

==== Uploading Files via HTML Form ====

To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to '''multipart/form-data''' for proper file handling. File uploads will '''ONLY''' work with the '''multipart/form-data''' enctype attribute.

Example:

<form id="theform" method="POST" action="upload" enctype="multipart/form-data">
<input type="file" name="myFile[]" multiple>
</form>

In this example:

*The multiple attribute allows users to select and upload multiple files.

*The uploaded file names are stored in an array for easy access.

==== Handling Uploaded Files in XAP ====

Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:

Q.MYFILE[0] - file1.xxx
Q.MYFILE[1] - file2.yyy

You can retrieve the file data using the new '''GET FILEDATA''' command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the '''PRINTFILE''' statement.

Example Usage:

filedata$ = control(0, "get filedata file1.xxx")
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$

This command writes the uploaded file to the TMP directory while preserving the original filename.

==== File Management ====

Retrieve Data: Use '''GET FILEDATA''' to access uploaded file content.

Save Files: Utilize '''PRINTFILE''' to store files in a specified directory.

New XAP controls and File Upload

2025-03-14T18:36:04Z

Justin:

== New XAP Controls and File Upload ==

=== New Controls ===

As of Comet version 540, we have introduced new controls to enhance XAP’s support for form input arrays and file uploads. These controls are designed to improve data handling while maintaining backward compatibility. If you do not enable these new features, your existing programs will continue to function as they did in previous XAP versions, ensuring a seamless transition.

----

==== WRITEEMPTYFIELDS (#XAP Setting) ====

Force XAP to write keys to the CGIFILE even if the value is empty.

By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have

<input type="text" name="stringinput" />

and the form is submitted with no text in the input field, then XAP will NOT write '''Q.STRINGINPUT''' into the CGIFILE.

By including

WRITEEMPTYFIELDS TRUE

into your #XAP file, even if the value in the text input is empty, there will be a '''Q.STRINGINPUT''' key in the CGIFILE, with a blank record for the value.

----

==== URLDECODEKEYS (#XAP Setting) ====

Tell XAP to decode special characters when writing the keys in the CGIFILE.

By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.

So if we have a input field for text named like this:

<input type="text" name="stringinput[]" />

XAP will write the key for this input field into the CGIFILE as '''Q.STRINGINPUT%5B%5D'''

By including

URLDECODEKEYS TRUE

into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''

----

==== GET FILEDATA (XAP Control) ====

Retrieve the data from an uploaded file inside an XAP program.

When a file is uploaded to XAP using the '''type="file"''' input attribute, the name is stored in the CGIFILE. For example:

<input type="file" name="myFile">

will display an HTML input element to upload a file. When a file is specified and submitted, the CGIFILE will contain:

Q.MYFILE - filename.ext

In order to retrieve the data from the upload, use the '''GET FILEDATA''' control to copy the file into a dynamic string:

filedata$ = control(0, "GET FILEDATA filename.ext")

From here you can use something like '''PRINTFILE''' to save the data to the filesystem.

Note, this method copies the entire file as a chunk of data into a dynamic string. Be aware that large files could cause performance issues depending on usage.

----

=== Array Handling for Form Elements ===

==== Overview ====

XAP now supports HTML form input arrays. This allows multiple values to be submitted under the same field name and stored in an indexed array. This functionality enhances data collection and processing for forms.

==== Defining an Input Array ====

To designate an input field as an array, append '''[]''' to its '''name''' attribute. Each value submitted will be stored as a zero-indexed array using the input name as the key.

Example:

<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">

This example creates four text input fields in an HTML form.

==== How XAP Handles Input Arrays ====

When submitted, the data will be stored in the CGIFILE with key/value pairs in the order they appear:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - second value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

The last key, '''Q.STRINGINPUT[]''', ensures backward compatibility with older XAP versions where only the last submitted value was stored.

==== URL Decoding of Keys ====

If '''URLDECODEKEYS TRUE''' is included in the #XAP file, the query keys will be properly decoded. Without this setting, the CGIFILE will store encoded keys:

Q.STRINGINPUT%5B0%5D - first value
Q.STRINGINPUT%5B1%5D - second value
Q.STRINGINPUT%5B2%5D - third value
Q.STRINGINPUT%5B3%5D - fourth value
Q.STRINGINPUT%5B%5D - fourth/last value

==== Handling Empty Values ====

By default, XAP does not write key/value pairs to CGIFILE if the field is left empty. For example, if the second input field is empty, the stored values would be:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

To force XAP to store all fields, including empty ones, use the '''WRITEEMPTYFIELDS TRUE''' setting. This ensures all key/value pairs are written:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - empty
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

==== Summary ====

*Use '''name="fieldname[]"''' in your '''<input>''' element to create input arrays.

*XAP stores submitted values as zero-indexed arrays.

*The last submitted value is also stored under '''Q.FIELDNAME[]''' for backward compatibility.

*Use '''URLDECODEKEYS TRUE''' to properly decode keys.

*By default, empty values are not stored; enable '''WRITEEMPTYFIELDS TRUE''' to include them.

----

=== New XAP File Upload Mechanics ===

==== Overview ====

XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.

==== Uploading Files via HTML Form ====

To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to '''multipart/form-data''' for proper file handling. File uploads will '''ONLY''' work with the '''multipart/form-data' enctype attribute.

Example:

<form id="theform" method="POST" action="upload" enctype="multipart/form-data">
<input type="file" name="myFile[]" multiple>
</form>

In this example:

*The multiple attribute allows users to select and upload multiple files.

*The uploaded file names are stored in an array for easy access.

==== Handling Uploaded Files in XAP ====

Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:

Q.MYFILE[0] - file1.xxx
Q.MYFILE[1] - file2.yyy

You can retrieve the file data using the new '''GET FILEDATA''' command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the '''PRINTFILE''' statement.

Example Usage:

filedata$ = control(0, "get filedata file1.xxx")
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$

This command writes the uploaded file to the TMP directory while preserving the original filename.

==== File Management ====

Retrieve Data: Use '''GET FILEDATA''' to access uploaded file content.

Save Files: Utilize '''PRINTFILE''' to store files in a specified directory.

New XAP controls and File Upload

2025-03-14T18:33:42Z

Justin:

== New XAP Controls and File Upload ==

=== New Controls ===

As of Comet version 540, we have introduced new controls to enhance XAP’s support for form input arrays and file uploads. These controls are designed to improve data handling while maintaining backward compatibility. If you do not enable these new features, your existing programs will continue to function as they did in previous XAP versions, ensuring a seamless transition.

----

==== WRITEEMPTYFIELDS (#XAP Setting) ====

Force XAP to write keys to the CGIFILE even if the value is empty.

By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have

<input type="text" name="stringinput" />

and the form is submitted with no text in the input field, then XAP will NOT write '''Q.STRINGINPUT''' into the CGIFILE.

By including

WRITEEMPTYFIELDS TRUE

into your #XAP file, even if the value in the text input is empty, there will be a '''Q.STRINGINPUT''' key in the CGIFILE, with a blank record for the value.

----

==== URLDECODEKEYS (#XAP Setting) ====

Tell XAP to decode special characters when writing the keys in the CGIFILE.

By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.

So if we have a input field for text named like this:

<input type="text" name="stringinput[]" />

XAP will write the key for this input field into the CGIFILE as '''Q.STRINGINPUT%5B%5D'''

By including

URLDECODEKEYS TRUE

into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''

----

==== GET FILEDATA (XAP Control) ====

Retrieve the data from an uploaded file inside an XAP program.

When a file is uploaded to XAP using the '''type="file"''' input attribute, the name is stored in the CGIFILE. For example:

<input type="file" name="myFile">

will display an HTML input element to upload a file. When a file is specified and submitted, the CGIFILE will contain:

Q.MYFILE - filename.ext

In order to retrieve the data from the upload, use the '''GET FILEDATA''' control to copy the file into a dynamic string:

filedata$ = control(0, "GET FILEDATA filename.ext")

From here you can use something like '''PRINTFILE''' to save the data to the filesystem.

Note, this method copies the entire file as a chunk of data into a dynamic string. Be aware that large files could cause performance issues depending on usage.

----

=== Array Handling for Form Elements ===

==== Overview ====

XAP now supports HTML form input arrays. This allows multiple values to be submitted under the same field name and stored in an indexed array. This functionality enhances data collection and processing for forms.

==== Defining an Input Array ====

To designate an input field as an array, append '''[]''' to its '''name''' attribute. Each value submitted will be stored as a zero-indexed array using the input name as the key.

Example:

<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">

This example creates four text input fields in an HTML form.

==== How XAP Handles Input Arrays ====

When submitted, the data will be stored in the CGIFILE with key/value pairs in the order they appear:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - second value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

The last key, '''Q.STRINGINPUT[]''', ensures backward compatibility with older XAP versions where only the last submitted value was stored.

==== URL Decoding of Keys ====

If '''URLDECODEKEYS TRUE''' is included in the #XAP file, the query keys will be properly decoded. Without this setting, the CGIFILE will store encoded keys:

Q.STRINGINPUT%5B0%5D - first value
Q.STRINGINPUT%5B1%5D - second value
Q.STRINGINPUT%5B2%5D - third value
Q.STRINGINPUT%5B3%5D - fourth value
Q.STRINGINPUT%5B%5D - fourth/last value

==== Handling Empty Values ====

By default, XAP does not write key/value pairs to CGIFILE if the field is left empty. For example, if the second input field is empty, the stored values would be:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

To force XAP to store all fields, including empty ones, use the '''WRITEEMPTYFIELDS TRUE''' setting. This ensures all key/value pairs are written:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - empty
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

==== Summary ====

*Use '''name="fieldname[]"''' in your '''<input>''' element to create input arrays.

*XAP stores submitted values as zero-indexed arrays.

*The last submitted value is also stored under '''Q.FIELDNAME[]''' for backward compatibility.

*Use '''URLDECODEKEYS TRUE''' to properly decode keys.

*By default, empty values are not stored; enable '''WRITEEMPTYFIELDS TRUE''' to include them.

----

=== New XAP File Upload Mechanics ===

==== Overview ====

XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.

==== Uploading Files via HTML Form ====

To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to '''multipart/form-data''' for proper file handling. File uploads will '''ONLY''' work with the '''multipart/form-data' enctype attribute - '''POST''' will NOT work.

Example:

<form id="theform" method="POST" action="upload" enctype="multipart/form-data">
<input type="file" name="myFile[]" multiple>
</form>

In this example:

*The multiple attribute allows users to select and upload multiple files.

*The uploaded file names are stored in an array for easy access.

==== Handling Uploaded Files in XAP ====

Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:

Q.MYFILE[0] - file1.xxx
Q.MYFILE[1] - file2.yyy

You can retrieve the file data using the new '''GET FILEDATA''' command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the '''PRINTFILE''' statement.

Example Usage:

filedata$ = control(0, "get filedata file1.xxx")
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$

This command writes the uploaded file to the TMP directory while preserving the original filename.

==== File Management ====

Retrieve Data: Use '''GET FILEDATA''' to access uploaded file content.

Save Files: Utilize '''PRINTFILE''' to store files in a specified directory.

New XAP controls and File Upload

2025-03-13T21:30:59Z

Justin:

== New XAP Controls and File Upload ==

=== New Controls ===

These new controls can be added to your #XAP file, and will change how XAP builds the keyed file containing query key/value pairs.

----

==== WRITEEMPTYFIELDS ====

Force XAP to write keys to the CGIFILE even if the value is empty.

By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have

<input type="text" name="stringinput" />

and the form is submitted with no text in the input field, then XAP will NOT write '''Q.STRINGINPUT''' into the CGIFILE.

By including

WRITEEMPTYFIELDS TRUE

into your #XAP file, even if the value in the text input is empty, there will be a '''Q.STRINGINPUT''' key in the CGIFILE, with a blank record for the value.

----

==== URLDECODEKEYS ====

Tell XAP to decode special characters when writing the keys in the CGIFILE.

By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.

So if we have a input field for text named like this:

<input type="text" name="stringinput[]" />

XAP will write the key for this input field into the CGIFILE as '''Q.STRINGINPUT%5B%5D'''

By including

URLDECODEKEYS TRUE

into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''

----

==== GET FILEDATA ====

Retrieve the data from an uploaded file inside an XAP program.

When a file is uploaded to XAP using the '''type="file"''' input attribute, the name is stored in the CGIFILE. For example:

<input type="file" name="myFile">

will display an HTML input element to upload a file. When a file is specified and submitted, the CGIFILE will contain:

Q.MYFILE - filename.ext

In order to retrieve the data from the upload, use the '''GET FILEDATA''' control to copy the file into a dynamic string:

filedata$ = control(0, "GET FILEDATA filename.ext")

From here you can use something like '''PRINTFILE''' to save the data to the filesystem.

Note, this method copies the entire file as a chunk of data into a dynamic string. Be aware that large files could cause performance issues depending on usage.

----

=== Array Handling for Form Elements ===

==== Overview ====

XAP now supports HTML form input arrays. This allows multiple values to be submitted under the same field name and stored in an indexed array. This functionality enhances data collection and processing for forms.

==== Defining an Input Array ====

To designate an input field as an array, append '''[]''' to its '''name''' attribute. Each value submitted will be stored as a zero-indexed array using the input name as the key.

Example:

<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">

This example creates four text input fields in an HTML form.

==== How XAP Handles Input Arrays ====

When submitted, the data will be stored in the CGIFILE with key/value pairs in the order they appear:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - second value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

The last key, '''Q.STRINGINPUT[]''', ensures backward compatibility with older XAP versions where only the last submitted value was stored.

==== URL Decoding of Keys ====

If '''URLDECODEKEYS TRUE''' is included in the #XAP file, the query keys will be properly decoded. Without this setting, the CGIFILE will store encoded keys:

Q.STRINGINPUT%5B0%5D - first value
Q.STRINGINPUT%5B1%5D - second value
Q.STRINGINPUT%5B2%5D - third value
Q.STRINGINPUT%5B3%5D - fourth value
Q.STRINGINPUT%5B%5D - fourth/last value

==== Handling Empty Values ====

By default, XAP does not write key/value pairs to CGIFILE if the field is left empty. For example, if the second input field is empty, the stored values would be:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

To force XAP to store all fields, including empty ones, use the '''WRITEEMPTYFIELDS TRUE''' setting. This ensures all key/value pairs are written:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - empty
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

==== Summary ====

*Use '''name="fieldname[]"''' in your '''<input>''' element to create input arrays.

*XAP stores submitted values as zero-indexed arrays.

*The last submitted value is also stored under '''Q.FIELDNAME[]''' for backward compatibility.

*Use '''URLDECODEKEYS TRUE''' to properly decode keys.

*By default, empty values are not stored; enable '''WRITEEMPTYFIELDS TRUE''' to include them.

----

=== New XAP File Upload Mechanics ===

==== Overview ====

XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.

==== Uploading Files via HTML Form ====

To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to '''multipart/form-data''' for proper file handling. File uploads will '''ONLY''' work with the '''multipart/form-data' enctype attribute - '''POST''' will NOT work.

Example:

<form id="theform" method="POST" action="upload" enctype="multipart/form-data">
<input type="file" name="myFile[]" multiple>
</form>

In this example:

*The multiple attribute allows users to select and upload multiple files.

*The uploaded file names are stored in an array for easy access.

==== Handling Uploaded Files in XAP ====

Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:

Q.MYFILE[0] - file1.xxx
Q.MYFILE[1] - file2.yyy

You can retrieve the file data using the new '''GET FILEDATA''' command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the '''PRINTFILE''' statement.

Example Usage:

filedata$ = control(0, "get filedata file1.xxx")
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$

This command writes the uploaded file to the TMP directory while preserving the original filename.

==== File Management ====

Retrieve Data: Use '''GET FILEDATA''' to access uploaded file content.

Save Files: Utilize '''PRINTFILE''' to store files in a specified directory.

New XAP controls and File Upload

2025-03-13T20:51:55Z

Justin:

== New XAP Controls and File Upload ==

=== New Controls ===

These new controls can be added to your #XAP file, and will change how XAP builds the keyed file containing query key/value pairs.

----

==== WRITEEMPTYFIELDS ====

Force XAP to write keys to the CGIFILE even if the value is empty.

By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have

<input type="text" name="stringinput" />

and the form is submitted with no text in the input field, then XAP will NOT write '''Q.STRINGINPUT''' into the CGIFILE.

By including

WRITEEMPTYFIELDS TRUE

into your #XAP file, even if the value in the text input is empty, there will be a '''Q.STRINGINPUT''' key in the CGIFILE, with a blank record for the value.

----

==== URLDECODEKEYS ====

Tell XAP to decode special characters when writing the keys in the CGIFILE.

By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.

So if we have a input field for text named like this:

<input type="text" name="stringinput[]" />

XAP will write the key for this input field into the CGIFILE as '''Q.STRINGINPUT%5B%5D'''

By including

URLDECODEKEYS TRUE

into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''

----

==== GET FILEDATA ====

Retrieve the data from an uploaded file inside an XAP program.

When a file is uploaded to XAP using the '''type="file"''' input attribute, the name is stored in the CGIFILE. For example:

<input type="file" name="myFile">

will display an HTML input element to upload a file. When a file is specified and submitted, the CGIFILE will contain:

Q.MYFILE - filename.ext

In order to retrieve the data from the upload, use the '''GET FILEDATA''' control to copy the file into a dynamic string:

filedata$ = control(0, "GET FILEDATA filename.ext")

Note, this method copies the entire file as a chunk of data into a dynamic string. If the file is large, then further copies or manipulation of the string

----

=== Array Handling for Form Elements ===

==== Overview ====

XAP now supports HTML form input arrays. This allows multiple values to be submitted under the same field name and stored in an indexed array. This functionality enhances data collection and processing for forms.

==== Defining an Input Array ====

To designate an input field as an array, append '''[]''' to its '''name''' attribute. Each value submitted will be stored as a zero-indexed array using the input name as the key.

Example:

<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">

This example creates four text input fields in an HTML form.

==== How XAP Handles Input Arrays ====

When submitted, the data will be stored in the CGIFILE with key/value pairs in the order they appear:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - second value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

The last key, '''Q.STRINGINPUT[]''', ensures backward compatibility with older XAP versions where only the last submitted value was stored.

==== URL Decoding of Keys ====

If '''URLDECODEKEYS TRUE''' is included in the #XAP file, the query keys will be properly decoded. Without this setting, the CGIFILE will store encoded keys:

Q.STRINGINPUT%5B0%5D - first value
Q.STRINGINPUT%5B1%5D - second value
Q.STRINGINPUT%5B2%5D - third value
Q.STRINGINPUT%5B3%5D - fourth value
Q.STRINGINPUT%5B%5D - fourth/last value

==== Handling Empty Values ====

By default, XAP does not write key/value pairs to CGIFILE if the field is left empty. For example, if the second input field is empty, the stored values would be:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

To force XAP to store all fields, including empty ones, use the '''WRITEEMPTYFIELDS TRUE''' setting. This ensures all key/value pairs are written:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - empty
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

==== Summary ====

*Use '''name="fieldname[]"''' in your '''<input>''' element to create input arrays.

*XAP stores submitted values as zero-indexed arrays.

*The last submitted value is also stored under '''Q.FIELDNAME[]''' for backward compatibility.

*Use '''URLDECODEKEYS TRUE''' to properly decode keys.

*By default, empty values are not stored; enable '''WRITEEMPTYFIELDS TRUE''' to include them.

----

=== New XAP File Upload Mechanics ===

==== Overview ====

XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.

==== Uploading Files via HTML Form ====

To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to '''multipart/form-data''' for proper file handling. File uploads will '''ONLY''' work with the '''multipart/form-data' enctype attribute - '''POST''' will NOT work.

Example:

<form id="theform" method="POST" action="upload" enctype="multipart/form-data">
<input type="file" name="myFile[]" multiple>
</form>

In this example:

*The multiple attribute allows users to select and upload multiple files.

*The uploaded file names are stored in an array for easy access.

==== Handling Uploaded Files in XAP ====

Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:

Q.MYFILE[0] - file1.xxx
Q.MYFILE[1] - file2.yyy

You can retrieve the file data using the new '''GET FILEDATA''' command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the '''PRINTFILE''' statement.

Example Usage:

filedata$ = control(0, "get filedata file1.xxx")
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$

This command writes the uploaded file to the TMP directory while preserving the original filename.

==== File Management ====

Retrieve Data: Use '''GET FILEDATA''' to access uploaded file content.

Save Files: Utilize '''PRINTFILE''' to store files in a specified directory.

New XAP controls and File Upload

2025-03-13T20:35:09Z

Justin:

== New XAP Controls and File Upload ==

=== New Controls ===

These new controls can be added to your #XAP file, and will change how XAP builds the keyed file containing query key/value pairs.

----

==== WRITEEMPTYFIELDS ====

Force XAP to write keys to the CGIFILE even if the value is empty.

By default, XAP will skip writing keys to the CGIFILE if the value in the key/value pair is empty. For instance, if you have

<input type="text" name="stringinput" />

and the form is submitted with no text in the input field, then XAP will NOT write '''Q.STRINGINPUT''' into the CGIFILE.

By including

WRITEEMPTYFIELDS TRUE

into your #XAP file, even if the value in the text input is empty, there will be a '''Q.STRINGINPUT''' key in the CGIFILE, with a blank record for the value.

----

==== URLDECODEKEYS ====

Tell XAP to decode special characters when writing the keys in the CGIFILE.

By default, XAP will NOT decode special characters inside the keys of the CGIFILE. Special characters include, for example, '(', '[', and '%' which are encoded as '%28', '%5B', and '%25' respectively.

So if we have a input field for text named like this:

<input type="text" name="stringinput[]" />

XAP will write the key for this input field into the CGIFILE as '''Q.STRINGINPUT%5B%5D'''

By including

URLDECODEKEYS TRUE

into your #XAP file, you can force XAP to write the encoded characters as they were originally intended. In this case, '''Q.STRINGINPUT[]'''

----

=== Array Handling for Form Elements ===

Starting in Comet 540, XAP supports HTML form input arrays. You can designate any <input> as an array element by including "[]" at the end of the name. Each value in a designated array will be written to a zero-indexed array using the <input> name as the key field. For example,

<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">
<input type="text" name="stringinput[]">

will display 4 text inputs in an HTML form. When submitted to XAP, the CGIFILE will contain the following key/value pairs:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - second value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

where each key/value corresponds to the element in the order in the HTML form. In order to be backwards compatible with previous versions of Comet/XAP, we include the last '''Q.STRINGINPUT[]''' as a key without an index, and the value of the last query value specified in the form. In previous versions, this would be the only key/value defined in the CGIFILE.

Note, this example assumes that '''URLDECODEKEYS TRUE''' was included in the #XAP file. By default, the query keys will not be decoded, and your CGIFILE will look like this:

Q.STRINGINPUT%5B0%5D - first value
Q.STRINGINPUT%5B1%5D - second value
Q.STRINGINPUT%5B2%5D - third value
Q.STRINGINPUT%5B3%5D - fourth value
Q.STRINGINPUT%5B%5D - fourth/last value

Using this example, if the second value is empty (no value), then the CGIFILE will contain the following key/value pairs:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

because, by default, XAP does not write key/value pairs to the CGIFILE that have empty values. Using the new control '''WRITEEMPTYFIELDS TRUE''' will force XAP to write all key/value pairs, regardless of whether the value is empty:

Q.STRINGINPUT[0] - first value
Q.STRINGINPUT[1] - empty
Q.STRINGINPUT[2] - third value
Q.STRINGINPUT[3] - fourth value
Q.STRINGINPUT[] - fourth/last value

----

=== New XAP File Upload Mechanics ===

==== Overview ====

XAP now supports file uploads, allowing web-enabled programs to upload and process files within the system. This feature enables users to upload multiple files and manage them dynamically.

==== Uploading Files via HTML Form ====

To upload files in XAP, use the <input type="file"> tag within an HTML form. Ensure that the enctype attribute is set to '''multipart/form-data''' for proper file handling. File uploads will '''ONLY''' work with the '''multipart/form-data' enctype attribute - '''POST''' will NOT work.

Example:

<form id="theform" method="POST" action="upload" enctype="multipart/form-data">
<input type="file" name="myFile[]" multiple>
</form>

In this example:

*The multiple attribute allows users to select and upload multiple files.

*The uploaded file names are stored in an array for easy access.

==== Handling Uploaded Files in XAP ====

Once uploaded, your CGIFILE will store the filenames as key/value pairs as follows:

Q.MYFILE[0] - file1.xxx
Q.MYFILE[1] - file2.yyy

You can retrieve the file data using the new '''GET FILEDATA''' command to copy the file data into a dynamic string and manipulate it as needed. For example, you can write it to the file system using the '''PRINTFILE''' statement.

Example Usage:

filedata$ = "get filedata file1.xxx"
newpath$ = path("TMP") + "file.xxx"
Printfile newpath$ filedata$

This command writes the uploaded file to the TMP directory while preserving the original filename.

==== File Management ====

Retrieve Data: Use '''GET FILEDATA''' to access uploaded file content.

Save Files: Utilize '''PRINTFILE''' to store files in a specified directory.

New XAP controls and File Upload

2025-03-13T20:18:08Z

Justin:

New XAP controls and File Upload

2025-03-13T19:08:15Z

Justin:

New XAP controls and File Upload

2025-03-12T23:55:58Z

Justin: Created page with "== New XAP Controls and File Upload == === New Controls === These new controls can be added to your #XAP file, and will change how XAP builds the keyed file containing query ke..."

Main Page

2025-03-12T23:27:28Z

Justin:

='''Comet by Signature Systems, Inc.'''=

* [[Getting Started With Comet]]

* [[Subscription Benefits]]

* [[Virtual Dongle]]

* [[FAQs]]

* [[CFILES - the replacement for DbMgr]]

* [[Comet Meetings]]

* [[Configuration and Installation]]

* [[Programming]]

* [[Comet32]]

* [[STL Containers]]

* [[Xap and Comet32]]

* [[Products]]

* [[Utilities]]

* [[Comet Tips]]

* [http://support.signature.net/ Support - Users Forum]

* [[How to edit this Wiki]]

* '''[http://cc.signature.net/guest/adduser Request ability to edit pages on this Wiki]'''

*[[Comet And RDP]]

* [[New XAP controls and File Upload]]

A hint from the old guy. The Wiki's text size is based on the browser's settings. In '''Firefox''' I set the minimum font size to 16.

Tools >> Options >> Content >> Advanced. Minimum font size.

Using the email printer

2024-01-09T22:06:52Z

Justin:

==Email Printing with Comet==
© 2007 Signature System Inc.

Within a few minutes you can configure a "printer" that will automatically email any text, HTML, or PDF document produced using Comet's printer drivers.

==Understanding SMTP==
The Email Printer uses a DES program called EMAILPTR. It talks the SMTP protocol.
SMTP stands for '''S'''imple '''M'''ail '''T'''ransport '''P'''rotocol. It is the basic protocol used to send mail over the internet. SMTP mimics the process of sending a package or letter by snail mail or delivery service. When mailing a physical letter, you first write the letter itself (the body), then write the envelope and then take the envelope to the post office, giving delivery instructions.

===There are 3 sections of an SMTP email transaction.===

====1. The SMTP routing instructions:====
* The connection server and port (Connect)
* The introduction (Domain)
* Optional Authentication (User and Password)
* The Sender's ID (Mail from)
* The destination (rcpt to)
* Other SMTP Commands

====2. The "envelope" or Header====
* The date
* From
* To
* Subject
* Other Header elements

====3. The body of the mail====
* Possibly multiple parts, each a different format.

==Requirements==

There are a few requirements to make this feature work.

* A WinSock gateway configured. It is better to configure multiple WinSock Gateways.
* A COM license for CometLib.
* A connection to the Internet.
* A reachable SMTP server.
* The TMP directory for Comet must be configured as a CFAM directory and it must be configured in SYSGEN using the $(CATEMP) alias:
00 = c ,$(catemp);

==Configuration==

You can designate TEXT, HTML, and PDF printers as email printers. Here is a sample of a section of an INI file:

Printer = leh,h,n,,htm,EmailPtr; ; Data records are limited to 254 bytes
Printer = leh,h,n,,htm,EmlPtr32; ; For Comet32 users only: no restriction on length of data records written to the printer
Printer = lep,p,n,,pdfFactory,EmailPtr;
Printer = let,x,n,,txt,EmailPtr; ; Data records are limited to 254 bytes
Printer = let,x,n,,txt,EmlPtr32; ; For Comet32 users only: no restriction on length of data records written to the printer

We could have named the printers any device name beginning with an "L". What designates this as an email printer is the DES program "EmailPtr" or "EmlPtr32". These DES programs are released as part of the REL Directory.

===Doc Manager===
You can configure a printer as both an email printer and an archive printer.

Printer = LPI,p,x,SPL:invoices,Adobe PDF,EmailPtr;

Every document printed to that printer would be rendered in PDF by the Adobe Pdf driver, emailed, and placed into the INVOICES docmanager archive. With appropriate Email.ini settings (see below), no program changes would be required other than selecting 'LPI' as the printer.

==Mnemonics==

There are several mnemonics specifically related to the email printer. First, you need to specify the smtp server name and port to be used to send your email.

Print (lun) (Server='smtp.ourserver.net mail')

Look at the server settings in your email program for the correct setting for this. The word "mail" above is an alias for port 25. Thus, you could have written

Print (lun) (Server='smtp.ourserver.net 25')

and accomplished the same thing. You can use any port mandated by your ISP. Port 25 is the default. If you do not specify a port as part of the server name, the email printer will attempt to use port 25. Note: Beginning with Comet 2006 you are able to send email from smtp servers that require authentication.

If you wish, you may also specify a domain name.

Print (lun) (Domain='signature.net')

If it is not specified, the email printer will supply the same domain as designated in the server mnemonic.

To specify the sender's name you use the "From" mnemonic.

Print (lun) (From='"jim guerber"<jim@@signature.net>')

This is used both for SMTP routing (MAIL FROM:) and for the mail message header (From:). It should be set to a valid email address.

Use the "To" mnemonic to specify your recipients. This will be used for SMTP routing (RCPT TO:) and the header (To:).

Print (lun) (To = 'jim<jim@@signature.net>')
Print (lun) (To = 'gina@@signature.net')

You must specify at least one recipient. Use multiple instances of this mnemonic to send your email to more than one recipient. CC and BCC recipients may be specified in addition to or instead of TO recipients.

Print (lun) (CC = 'barbara@@signature.net')
Print (lun) (BCC = 'brian@@signature.net')

You must include a subject for your email, use the "Subject" mnemonic.

Print (lun) (Subject='The Subject of this email')

In addition to whatever is written to the email printer, you may want to include body text. Depending on your email client, for html printers body text will either appear in an attachment, since it is usual for HTML to appear as the main body of the email, or it will be appended following the html content. For PDF printers, this text will be the main body of the email and the PDF will appear as an attachment. For text printers, the body text will appear just before the printer output. To specify body text, use the "Text" mnemonic.

Print (lun) (Text='yada yada yada')

The email printer will optionally write to a log file, recording details about each email sent, including responses from the smtp server. The log file is a text file located on any directory to which the user has access. The email printer will append to this log file. The log file may optionally be erased before the print job is run. Otherwise, it is up to the administrator or outside program to erase this file periodically.

Print (lun) (Log='file','dir','erase')

If the log file name is not specified, a file named "email.log" will be used. If the email directory is not specified, "COS" will be used. By default, the file will not be erased. If there is no LOG statement at all, no log file will be generated.

If you wish to specify a name for an attachment to your email, use the (EmailDocument=) mnemonic.

Print (lun) (EmailDocument='file')
Without the (EmailDocument=) mnemonic, the attachment would carry the default name of the document.

==Formatting of email addresses==

In the examples above, we have shown a few different ways to specify an email address. Mail programs like addresses formatted in the following way: "FirstName LastName"<email@domain.tld> Any of the following should work:

Print (lun) (To = 'Jim Guerber<jim@@signature.net>') ! Best
Print (lun) (To = 'Jim<jim@@signature.net>') ! ok
Print (lun) (To = 'jim@@signature.net') ! worst

If there is no space character in the name the double quotes are not necessary. Most email programs will take some sort of shortened form of email address, even just the address with no <> such as email@domain.tld, but some spam detection programs may object to this simple form. Note the use of double @ characters as an escape convention of Internet Basic.

Email addresses used in the SMTP routing instructions "mail from" and "rcpt to" will have any name information (like "Jim Guerber" in the above example) stripped out. Microsoft Exchange Server doesn't tolerate anything other than the simple email address.

== A Note on Verifying Email Addresses==

If you're going to do email address validation, consider that VRFY and EXPN are blocked by most ISPs nowadays. Also, simulating VRFY by stacking RCPT TO: commands is something that spammers do. ISPs know this, and the smarter ones track how often you do this. You'll get blocked after some number of attempts. I wouldn't go looking for a lot of sympathy from ISPs when trying to get unblocked afterwards, as the ISPs consider this a very bad practice that good guys don't engage in.
==The email.ini file==

Several settings for email printers never (or rarely) change. These settings can be placed in an initialization file (INI File). The email printer will look for a file named email.ini which can contain those settings. The email.ini file is optional since all values may be supplied by mnemonics in the program, but it may be a more convenient way to supply some parameters such as the smtp server name. Lines beginning with an exclamation marks ! are treated as comments.

====Mnemonics vs the Email.ini file====
The information required for an email may be either specified by the use of mnemonics, or placed in a text file called email.ini or both. You may want to setup a standard email.ini file containing items that remain constant from one email to another such as server and domain, and specify the rest of the info using mnemonics, or you may want to write a new email.ini file in the temp directory containing all of the information required before initiating the email program.
* The email.ini file is not processed until the printer is closed. This means that any time during the execution of the print program, you may add items to the email.ini file.
* Each print of a mnemonic causes a new line to be generated in the document (the email body) unless Transparent mode is specified (TR).
* Use of the email.ini file allows general print programs to generate email with no change.

The email printer will look for an equal sign (=) as a delimiter between the parameter name and the value. If an equal sign is not found, the whole line will be treated as text. This is the same as using the "text=" parameter. Here's an example:

server = smtp.ourserver.net
from = OrderProcessing@OurCompany.com
bcc = AcctsReceivable@OurCompany.com
subject = Thank you for your order
Thank you for your recent order. The attached document contains your invoice and delivery schedule.

Using the preceding email.ini file, all that the program would need to supply is the recipient's email address (using the (To=) mnemonic) and write the unique details of the message to the email printer. Note that Accounts Receivable will automatically receive a copy (bcc) of each email.

Some mnemonics supplied by the program have precedence over the email.ini settings. In other cases both values from a mnemonic AND values from the email.ini file will be used. Those mnemonics which will super cede the equivalent setting in the email.ini file are Server, Domain, From, Subject, and Log. And, if you were to try to use more than one of any of those mnemonics for a given email, only the first one of each would be used. The other settings: To, CC, BCC, and Text, may have multiple occurrences. And, if you use these mnemonics and have equivalent settings in the email.ini, they will all be processed for your email.

==Attachments==

Before understanding attachments, It is good to know the order documents get placed in the email for various printers. For the sake of this document we will call any text specified by the (text=)mnemonic or in the email.ini file "body text". For all email print jobs there are three possible components that are transmitted. The order depends on the printer type.

For HTML printers, the email is composed of the HTML generated for the printer, followed by the body text, and then any attachments specified.

For Text printers, email is composed of the printer output followed by body text and then attachments.

For PDF printers, the email is composed of body text, followed by the printer output as an attachment and then followed by any other attachments specified.

To add an attachment to the email document, either use the (attachment=path) mnemonic or specify the attachment in the INI file. The path specified must be a valid windows path (use either drive letter or UNC conventions), and does not need to be a Comet file or reside in a Comet directory. Any number of attachment files may be specified. The Emailptr program attempts to determine the mime type of the file by reading the mime keyed file in the rel directory using the file extent ion as the key. If the mime type is not determine able, the default mime type of "application/octet-stream" is used.

==Return Receipts==

Occasionally you may want to know when the receiver of your email reads it. Some (not all) email programs support the "Return-Receipt-To:" command. You may specify (a single) return receipt address either in the ini file or by using the (rr=) mnemonic. Following the equal sign must be a valid email address.

==Silent Running==

The Emailptr will sometimes put up a message box if some component of the email such as the subject is missing. This will stop any program that is designed to produce a series of emails, and would crash if run from a background partition. For that reason, there is an extra instruction in the email.ini file to take care of this situation. If you do not want the emailptr to send any output to the screen, include the '''silent''' command in the email.ini file. If this command appears alone, the emailptr will simply close the email and continue. You may also optionally specify a program to be entered each time an error is encountered. In that case, # buffer will contain the error information (the text that would normally appear in the message box.

==Other SMTP commands and header lines==

You may want to supply other commands to the SMTP server or place additional commands in the header. There are 2 commands that allow you to do that.

'''SmtpCmd=text''' includes the text into the smtp routing instructions. I can't find any good examples of why you would want to send one of these things, but in the future, some Exchange server or something may require one of these.

'''Smtphdr=text''' includes the text in the envelope (the header). There are several interesting commands you could want to put here, but most of them are obsolete.

Examples are:

print (LUN)(SmtpHdr='X-Priority: 1') ! mark the email as urgent

==Reference==

For reference, here is a complete list of mnemonics and their corresponding email.ini file settings:
{| border="1" cellpadding="2"
|-
!width="225"| Mnemonic
!width="400"| Ini file
|-
| (log = log$)
| log = email.log,cos,cycle
|-
| (server = server$)
| server = smtp.ourserver.net
|-
| (domain= domain$)
| domain= smtp.ourserver.net
|-
| (user = user$)
| user = username
|-
| (password= pw$)
| password = MyPassword
|-
| (from = from$)
| from = OrderProcessing@OurCompany.com
|-
| (to = to$)
| to = youraddress@yourisp.net
|-
| (cc = cc$)
| cc = mylawyer@protectme.net
|-
| (rr= ReturnReceipt$)
| rr = returnReceipt@OurCompany.com
|-
| (bcc = bcc$)
| bcc = AcctsReceivable@OurCompany.com
|-
| (subject = Subject$)
| subject = Thank you for your order
|-
| (attachment = a$)
| attachment = c:\boilerplate\terms.pdf
|-
| (silent = 'myprog')
| silent = myprog
|-
| (SmtpCmd = 'help')
| SmtpCmd=help
|-
| (SmtpHdr=h$)
| SmtpHdr=X-Priority: 1
|-
|
| ssl=true
|-
|
| tls=true
|-
|
| time = +/-#### (offset hours from GMT)
|-
|}

==Notes==
Here is an interesting article aimed at writers of smtp servers with techniques for filtering spam. It is useful to us so that we can better format our emails to avoid being labeled as "ratware".

[http://slett.net/spam-filtering-for-mx/ Spam Filtering for Mail Exchangers]

Using the email printer

2024-01-09T22:06:26Z

Justin:

==Email Printing with Comet==
© 2007 Signature System Inc.

Within a few minutes you can configure a "printer" that will automatically email any text, HTML, or PDF document produced using Comet's printer drivers.

==Understanding SMTP==
The Email Printer uses a DES program called EMAILPTR. It talks the SMTP protocol.
SMTP stands for '''S'''imple '''M'''ail '''T'''ransport '''P'''rotocol. It is the basic protocol used to send mail over the internet. SMTP mimics the process of sending a package or letter by snail mail or delivery service. When mailing a physical letter, you first write the letter itself (the body), then write the envelope and then take the envelope to the post office, giving delivery instructions.

===There are 3 sections of an SMTP email transaction.===

====1. The SMTP routing instructions:====
* The connection server and port (Connect)
* The introduction (Domain)
* Optional Authentication (User and Password)
* The Sender's ID (Mail from)
* The destination (rcpt to)
* Other SMTP Commands

====2. The "envelope" or Header====
* The date
* From
* To
* Subject
* Other Header elements

====3. The body of the mail====
* Possibly multiple parts, each a different format.

==Requirements==

There are a few requirements to make this feature work.

* A WinSock gateway configured. It is better to configure multiple WinSock Gateways.
* A COM license for CometLib.
* A connection to the Internet.
* A reachable SMTP server.
* The TMP directory for Comet must be configured as a CFAM directory and it must be configured in SYSGEN using the $(CATEMP) alias:
00 = c ,$(catemp);

==Configuration==

You can designate TEXT, HTML, and PDF printers as email printers. Here is a sample of a section of an INI file:

Printer = leh,h,n,,htm,EmailPtr; ; Data records are limited to 254 bytes
Printer = leh,h,n,,htm,EmlPtr32; ; For Comet32 users only: no restriction on length of data records written to the printer
Printer = lep,p,n,,pdfFactory,EmailPtr;
Printer = let,x,n,,txt,EmailPtr; ; Data records are limited to 254 bytes
Printer = let,x,n,,txt,EmlPtr32; ; For Comet32 users only: no restriction on length of data records written to the printer

We could have named the printers any device name beginning with an "L". What designates this as an email printer is the DES program "EmailPtr" or "EmlPtr32". These DES programs are released as part of the REL Directory.

===Doc Manager===
You can configure a printer as both an email printer and an archive printer.

Printer = LPI,p,x,SPL:invoices,Adobe PDF,EmailPtr;

Every document printed to that printer would be rendered in PDF by the Adobe Pdf driver, emailed, and placed into the INVOICES docmanager archive. With appropriate Email.ini settings (see below), no program changes would be required other than selecting 'LPI' as the printer.

==Mnemonics==

There are several mnemonics specifically related to the email printer. First, you need to specify the smtp server name and port to be used to send your email.

Print (lun) (Server='smtp.ourserver.net mail')

Look at the server settings in your email program for the correct setting for this. The word "mail" above is an alias for port 25. Thus, you could have written

Print (lun) (Server='smtp.ourserver.net 25')

and accomplished the same thing. You can use any port mandated by your ISP. Port 25 is the default. If you do not specify a port as part of the server name, the email printer will attempt to use port 25. Note: Beginning with Comet 2006 you are able to send email from smtp servers that require authentication.

If you wish, you may also specify a domain name.

Print (lun) (Domain='signature.net')

If it is not specified, the email printer will supply the same domain as designated in the server mnemonic.

To specify the sender's name you use the "From" mnemonic.

Print (lun) (From='"jim guerber"<jim@@signature.net>')

This is used both for SMTP routing (MAIL FROM:) and for the mail message header (From:). It should be set to a valid email address.

Use the "To" mnemonic to specify your recipients. This will be used for SMTP routing (RCPT TO:) and the header (To:).

Print (lun) (To = 'jim<jim@@signature.net>')
Print (lun) (To = 'gina@@signature.net')

You must specify at least one recipient. Use multiple instances of this mnemonic to send your email to more than one recipient. CC and BCC recipients may be specified in addition to or instead of TO recipients.

Print (lun) (CC = 'barbara@@signature.net')
Print (lun) (BCC = 'brian@@signature.net')

You must include a subject for your email, use the "Subject" mnemonic.

Print (lun) (Subject='The Subject of this email')

In addition to whatever is written to the email printer, you may want to include body text. Depending on your email client, for html printers body text will either appear in an attachment, since it is usual for HTML to appear as the main body of the email, or it will be appended following the html content. For PDF printers, this text will be the main body of the email and the PDF will appear as an attachment. For text printers, the body text will appear just before the printer output. To specify body text, use the "Text" mnemonic.

Print (lun) (Text='yada yada yada')

The email printer will optionally write to a log file, recording details about each email sent, including responses from the smtp server. The log file is a text file located on any directory to which the user has access. The email printer will append to this log file. The log file may optionally be erased before the print job is run. Otherwise, it is up to the administrator or outside program to erase this file periodically.

Print (lun) (Log='file','dir','erase')

If the log file name is not specified, a file named "email.log" will be used. If the email directory is not specified, "COS" will be used. By default, the file will not be erased. If there is no LOG statement at all, no log file will be generated.

If you wish to specify a name for an attachment to your email, use the (EmailDocument=) mnemonic.

Print (lun) (EmailDocument='file')
Without the (EmailDocument=) mnemonic, the attachment would carry the default name of the document.

==Formatting of email addresses==

In the examples above, we have shown a few different ways to specify an email address. Mail programs like addresses formatted in the following way: "FirstName LastName"<email@domain.tld> Any of the following should work:

Print (lun) (To = 'Jim Guerber<jim@@signature.net>') ! Best
Print (lun) (To = 'Jim<jim@@signature.net>') ! ok
Print (lun) (To = 'jim@@signature.net') ! worst

If there is no space character in the name the double quotes are not necessary. Most email programs will take some sort of shortened form of email address, even just the address with no <> such as email@domain.tld, but some spam detection programs may object to this simple form. Note the use of double @ characters as an escape convention of Internet Basic.

Email addresses used in the SMTP routing instructions "mail from" and "rcpt to" will have any name information (like "Jim Guerber" in the above example) stripped out. Microsoft Exchange Server doesn't tolerate anything other than the simple email address.

== A Note on Verifying Email Addresses==

If you're going to do email address validation, consider that VRFY and EXPN are blocked by most ISPs nowadays. Also, simulating VRFY by stacking RCPT TO: commands is something that spammers do. ISPs know this, and the smarter ones track how often you do this. You'll get blocked after some number of attempts. I wouldn't go looking for a lot of sympathy from ISPs when trying to get unblocked afterwards, as the ISPs consider this a very bad practice that good guys don't engage in.
==The email.ini file==

Several settings for email printers never (or rarely) change. These settings can be placed in an initialization file (INI File). The email printer will look for a file named email.ini which can contain those settings. The email.ini file is optional since all values may be supplied by mnemonics in the program, but it may be a more convenient way to supply some parameters such as the smtp server name. Lines beginning with an exclamation marks ! are treated as comments.

====Mnemonics vs the Email.ini file====
The information required for an email may be either specified by the use of mnemonics, or placed in a text file called email.ini or both. You may want to setup a standard email.ini file containing items that remain constant from one email to another such as server and domain, and specify the rest of the info using mnemonics, or you may want to write a new email.ini file in the temp directory containing all of the information required before initiating the email program.
* The email.ini file is not processed until the printer is closed. This means that any time during the execution of the print program, you may add items to the email.ini file.
* Each print of a mnemonic causes a new line to be generated in the document (the email body) unless Transparent mode is specified (TR).
* Use of the email.ini file allows general print programs to generate email with no change.

The email printer will look for an equal sign (=) as a delimiter between the parameter name and the value. If an equal sign is not found, the whole line will be treated as text. This is the same as using the "text=" parameter. Here's an example:

server = smtp.ourserver.net
from = OrderProcessing@OurCompany.com
bcc = AcctsReceivable@OurCompany.com
subject = Thank you for your order
Thank you for your recent order. The attached document contains your invoice and delivery schedule.

Using the preceding email.ini file, all that the program would need to supply is the recipient's email address (using the (To=) mnemonic) and write the unique details of the message to the email printer. Note that Accounts Receivable will automatically receive a copy (bcc) of each email.

Some mnemonics supplied by the program have precedence over the email.ini settings. In other cases both values from a mnemonic AND values from the email.ini file will be used. Those mnemonics which will super cede the equivalent setting in the email.ini file are Server, Domain, From, Subject, and Log. And, if you were to try to use more than one of any of those mnemonics for a given email, only the first one of each would be used. The other settings: To, CC, BCC, and Text, may have multiple occurrences. And, if you use these mnemonics and have equivalent settings in the email.ini, they will all be processed for your email.

==Attachments==

Before understanding attachments, It is good to know the order documents get placed in the email for various printers. For the sake of this document we will call any text specified by the (text=)mnemonic or in the email.ini file "body text". For all email print jobs there are three possible components that are transmitted. The order depends on the printer type.

For HTML printers, the email is composed of the HTML generated for the printer, followed by the body text, and then any attachments specified.

For Text printers, email is composed of the printer output followed by body text and then attachments.

For PDF printers, the email is composed of body text, followed by the printer output as an attachment and then followed by any other attachments specified.

To add an attachment to the email document, either use the (attachment=path) mnemonic or specify the attachment in the INI file. The path specified must be a valid windows path (use either drive letter or UNC conventions), and does not need to be a Comet file or reside in a Comet directory. Any number of attachment files may be specified. The Emailptr program attempts to determine the mime type of the file by reading the mime keyed file in the rel directory using the file extent ion as the key. If the mime type is not determine able, the default mime type of "application/octet-stream" is used.

==Return Receipts==

Occasionally you may want to know when the receiver of your email reads it. Some (not all) email programs support the "Return-Receipt-To:" command. You may specify (a single) return receipt address either in the ini file or by using the (rr=) mnemonic. Following the equal sign must be a valid email address.

==Silent Running==

The Emailptr will sometimes put up a message box if some component of the email such as the subject is missing. This will stop any program that is designed to produce a series of emails, and would crash if run from a background partition. For that reason, there is an extra instruction in the email.ini file to take care of this situation. If you do not want the emailptr to send any output to the screen, include the '''silent''' command in the email.ini file. If this command appears alone, the emailptr will simply close the email and continue. You may also optionally specify a program to be entered each time an error is encountered. In that case, # buffer will contain the error information (the text that would normally appear in the message box.

==Other SMTP commands and header lines==

You may want to supply other commands to the SMTP server or place additional commands in the header. There are 2 commands that allow you to do that.

'''SmtpCmd=text''' includes the text into the smtp routing instructions. I can't find any good examples of why you would want to send one of these things, but in the future, some Exchange server or something may require one of these.

'''Smtphdr=text''' includes the text in the envelope (the header). There are several interesting commands you could want to put here, but most of them are obsolete.

Examples are:

print (LUN)(SmtpHdr='X-Priority: 1') ! mark the email as urgent

==Reference==

For reference, here is a complete list of mnemonics and their corresponding email.ini file settings:
{| border="1" cellpadding="2"
|-
!width="225"| Mnemonic
!width="400"| Ini file
|-
| (log = log$)
| log = email.log,cos,cycle
|-
| (server = server$)
| server = smtp.ourserver.net
|-
| (domain= domain$)
| domain= smtp.ourserver.net
|-
| (user = user$)
| user = username
|-
| (password= pw$)
| password = MyPassword
|-
| (from = from$)
| from = OrderProcessing@OurCompany.com
|-
| (to = to$)
| to = youraddress@yourisp.net
|-
| (cc = cc$)
| cc = mylawyer@protectme.net
|-
| (rr= ReturnReceipt$)
| rr = returnReceipt@OurCompany.com
|-
| (bcc = bcc$)
| bcc = AcctsReceivable@OurCompany.com
|-
| (subject = Subject$)
| subject = Thank you for your order
|-
| (attachment = a$)
| attachment = c:\boilerplate\terms.pdf
|-
| (silent = 'myprog')
| silent = myprog
|-
| (SmtpCmd = 'help')
| SmtpCmd=help
|-
| (SmtpHdr=h$)
| SmtpHdr=X-Priority: 1
|-
|
| ssl=true
|-
|
| tls=true
|-
|
| time = '+/-####' (offset hours from GMT)
|-
|}

==Notes==
Here is an interesting article aimed at writers of smtp servers with techniques for filtering spam. It is useful to us so that we can better format our emails to avoid being labeled as "ratware".

[http://slett.net/spam-filtering-for-mx/ Spam Filtering for Mail Exchangers]

STL Container IB Reference

2023-10-13T21:46:38Z

Justin:

===Core Functions===
These are the main functions you will use for each container.

====Vector====
'''stlPushBack( <container-name>, <data> )''' adds an element to the end of the vector
'''stlPopBack( <container-name> )''' removes the element at the end of the vector
'''stlFront( <container-name> [,EXCP=statement label])''' gets the element at the front of the vector
'''stlBack( <container-name> [,EXCP=statement label])''' gets the element at the end of the vector
'''stlGet( <container-name>, <index> [,EXCP=statement label])''' gets the element at the index specified
'''stlSet( <container-name> <index> <data>)''' sets the element at the index specified

Similar to arrays, vectors are mostly used to access data based on a numeric index, thus stlGet and stlSet are going to be your bread and butter functions for this container. stlPushBack is a great way to programatically build a vector - it will append the specified data to the end of the vector, and increase its size by 1. If you want to remove the last element, you would use stlPopBack. Then the stlFront and stlBack functions have been included as shortcuts for accessing the first and last elements respectively.

====List====
'''stlPushBack( <container-name>, <data> )''' adds an element to the end of the list
'''stlPopBack( <container-name> )''' removes the element at the end of the list
'''stlPushFront( <container-name>, <data> )''' adds an element to the beginning of the list
'''stlPopFront( <container-name> )''' removes the element at the beginning of the list
'''stlFront( <container-name> [,EXCP=statement label])''' gets the element at the beginning of the list
'''stlBack( <container-name> [,EXCP=statement label])''' gets the element at the end of the list

Lists are designed to be accessed sequentially, that is each element is associated with the preceding and following elements in the container. As such, the core functions provided are used to add, remove, and get the elements at the front and back of the list. The real power of lists is utilized during iteration - they are the most efficient container for inserting and erasing elements in the middle of the container.

====Map====
'''stlGet( <container-name>, <key> [,EXCP=statement label])''' gets the element at the key specified
'''stlSet( <container-name> <key> <data>)''' sets the element at the key specified

Maps are used to relate an element to a key (string index). Similar to vectors, to access a value, the key must be specified.

====Stack/Queue====
'''stlPush( <container-name>, <data> )''' adds an element to the container
'''stlPop( <container-name> )''' removes the next element from the container
'''stlPeek( <container-name> [,EXCP=statement label])''' gets the next element from the container
'''stlGet( <container-name>, <index> [,EXCP=statement label])''' gets the element at the index specified
'''stlSet( <container-name> <index> <data>)''' sets the element at the index specified

Both stacks and queues utilize the same set of functions, but perform differently depending on which container you have implemented. In general, the stlPush, stlPop, and stlPeek functions are going to be the most important of these functions. They perform the basic operations associated with these containers. For stacks, stlPush and stlPop adds and removes from the end of the container. For queues, stlPush adds to the end of the container, and stlPop removes from the front of the container. For both containers, stlPeek will get the "next" element in the container (i.e. the last element for stacks, the first element for queues).

Because these containers are implemented with deques internally, we also provide access via numeric indexes with the stlSet() and stlGet() operators. These functions behave similarly to the vector functions of the same name, by getting and setting the elements at the specified index.

===Iteration Functions===
These functions are used to iterate over the elements of a container.

General:
'''stlBegin( <container-name> )''' sets the iterator position at the beginning
'''stlEnd( <container-name> )''' sets the iterator position at the end
'''stlNext( <container-name> ) [, EXCP=statement label]''' moves the iterator position forward one element
'''stlPrev( <container-name> )''' moves the iterator position back one element
'''stlRead( <container-name> [,EXCP=statement label])''' gets the element at the current iterator position
'''stlWrite( <container-name>, <data> )''' - sets the element at the current iterator position

Maps only:
'''stlReadKey( <container-name> [,EXCP=statement label])''' gets the key at the current iterator position

Lists only:
'''stlInsert( <container-name>, <data> )''' inserts the element BEFORE the current iterator position
'''stlErase( <container-name> )''' erases the element at the current iterator position
(stlErase will subsequently move the iterator position to the next element)

===Utility Functions===
These are basic functions that return information about the specified container.

'''stlSize( <container-name> [,EXCP=statement label])''' returns the size of the container
'''stlEmpty( <container-name> [,EXCP=statement label])''' returns whether the container is empty
'''stlClear( <container-name> )''' empties the specified container
'''stlReset( <container-name> )''' resets the container to its initial values

===Meta Functions===
These functions perform some action either on all of the elements in the container, or using all the elements in the container.

Retrieving and Installing your license certificate

2023-07-01T00:38:59Z

Justin:

SecLic - Comet License Retrieval / Installation Utility

SecLic is a utility which allows the retrieval and/or installation of the latest license certificate for your Comet Security Server. The license will be retrieved directly from a Signature Systems server and will be the most recent one issued for your security token. SecLic may be run either directly as a user utility or incorporated into your own application and ENTERed to run silently. Just be sure to have a WinSock gateway configured (a type 3 gateway).

To run it directly simply run SecLic from READY:

[[image:SecLic.jpg]]

To run it silently from your own app, you pass your choice of options via # buffer this way:

print (#) "OPT 1"

enter "SecLic" dir="REL"

input (#) Result$

There are 3 options:

* 1 - retrieve the latest certificate from the server and put it in the CometServices folder
* 2 - activate whatever certificate is in the CometServices folder
* 3 - retrieve and then activate
* 4 - retrieve expiration dates and license counts for currently installed certificate

The message you pass via the # buffer is case insensitive and any number of blanks are allowed between "opt" and the number. If the first 3 bytes of the buffer are anything other than ucase("opt") the dialog will display instead of running silently.

The result string will indicate the success or failure of the operation(s). It will begin with either "+OK" or "-ERR" and be followed by a descriptive message.

This utility is available on both Comet16 and Comet32 and for both USB and parallel plugs.

SecLic was added to the REL release in version 10.02 and requires Comet version .413 or higher and Comet Security Server version 10.0 or higher.

----

=== Notes for Option 4 ===

Option 4 was first released with Comet Security Server version 23.0, and requires REL version 23.01

When run directly, the seclic program will have a button on the top of the screen titled "Check currently installed certificate" which, when pressed, will pop up a message box with license counts and expiration dates for your currently installed certificate.

[[image:Seclic-new.png]] [[image:Seclic-newmsg.png]]

When ENTERed, specifying "OPT 4" will return the data in a 31 byte string with the following format:

<nowiki>
Position Length Description
===========================================================
1 8 Certificate Expiration Date
9 8 XAP Expiration Date (if applicable)
17 5 Number of Full Comet licenses
22 5 Number of Comet Anywhere licenses
27 5 Number of XAP licenses
</nowiki>

If an error occurs, the return string will have the following format: "-ERR -- error message"

File:Seclic-newmsg.png

2023-07-01T00:36:33Z

Justin:

Retrieving and Installing your license certificate

2023-07-01T00:36:02Z

Justin:

SecLic - Comet License Retrieval / Installation Utility

SecLic is a utility which allows the retrieval and/or installation of the latest license certificate for your Comet Security Server. The license will be retrieved directly from a Signature Systems server and will be the most recent one issued for your security token. SecLic may be run either directly as a user utility or incorporated into your own application and ENTERed to run silently. Just be sure to have a WinSock gateway configured (a type 3 gateway).

To run it directly simply run SecLic from READY:

[[image:SecLic.jpg]]

To run it silently from your own app, you pass your choice of options via # buffer this way:

print (#) "OPT 1"

enter "SecLic" dir="REL"

input (#) Result$

There are 3 options:

* 1 - retrieve the latest certificate from the server and put it in the CometServices folder
* 2 - activate whatever certificate is in the CometServices folder
* 3 - retrieve and then activate
* 4 - retrieve expiration dates and license counts for currently installed certificate

The message you pass via the # buffer is case insensitive and any number of blanks are allowed between "opt" and the number. If the first 3 bytes of the buffer are anything other than ucase("opt") the dialog will display instead of running silently.

The result string will indicate the success or failure of the operation(s). It will begin with either "+OK" or "-ERR" and be followed by a descriptive message.

This utility is available on both Comet16 and Comet32 and for both USB and parallel plugs.

SecLic was added to the REL release in version 10.02 and requires Comet version .413 or higher and Comet Security Server version 10.0 or higher.

----

=== Notes for Option 4 ===

Option 4 was first released with Comet Security Server version 23.0, and requires REL version 23.01

When run directly, the seclic program will have a button on the top of the screen titled "Check currently installed certificate" which, when pressed, will pop up a message box with license counts and expiration dates for your currently installed certificate.

[[image:Seclic-new.png]] [[image::Seclic-newmsg.png]]

When ENTERed, specifying "OPT 4" will return the data in the following format:

<nowiki>
Position Length Description
===========================================================
1 8 Certificate Expiration Date
9 8 XAP Expiration Date (if applicable)
17 5 Number of Full Comet licenses
22 5 Number of Comet Anywhere licenses
27 5 Number of XAP licenses
</nowiki>

If an error occurs, the return string will have the following format: "-ERR -- error message"

Retrieving and Installing your license certificate

2023-07-01T00:34:15Z

Justin:

SecLic - Comet License Retrieval / Installation Utility

SecLic is a utility which allows the retrieval and/or installation of the latest license certificate for your Comet Security Server. The license will be retrieved directly from a Signature Systems server and will be the most recent one issued for your security token. SecLic may be run either directly as a user utility or incorporated into your own application and ENTERed to run silently. Just be sure to have a WinSock gateway configured (a type 3 gateway).

To run it directly simply run SecLic from READY:

[[image:SecLic.jpg]]

To run it silently from your own app, you pass your choice of options via # buffer this way:

print (#) "OPT 1"

enter "SecLic" dir="REL"

input (#) Result$

There are 3 options:

* 1 - retrieve the latest certificate from the server and put it in the CometServices folder
* 2 - activate whatever certificate is in the CometServices folder
* 3 - retrieve and then activate
* 4 - retrieve expiration dates and license counts for currently installed certificate

The message you pass via the # buffer is case insensitive and any number of blanks are allowed between "opt" and the number. If the first 3 bytes of the buffer are anything other than ucase("opt") the dialog will display instead of running silently.

The result string will indicate the success or failure of the operation(s). It will begin with either "+OK" or "-ERR" and be followed by a descriptive message.

This utility is available on both Comet16 and Comet32 and for both USB and parallel plugs.

SecLic was added to the REL release in version 10.02 and requires Comet version .413 or higher and Comet Security Server version 10.0 or higher.

----

=== Notes for Option 4 ===

Option 4 was first released with Comet Security Server version 23.0, and requires REL version 23.01

When run directly, the seclic program will have a button on the top of the screen titled "Check currently installed certificate" which, when pressed, will pop up a message box with license counts and expiration dates for your currently installed certificate.

[[image:Seclic-new.png]]

When ENTERed, specifying "OPT 4" will return the data in the following format:

<nowiki>
Position Length Description
===========================================================
1 8 Certificate Expiration Date
9 8 XAP Expiration Date (if applicable)
17 5 Number of Full Comet licenses
22 5 Number of Comet Anywhere licenses
27 5 Number of XAP licenses
</nowiki>

If an error occurs, the return string will have the following format: "-ERR -- error message"

Retrieving and Installing your license certificate

2023-07-01T00:31:16Z

Justin:

SecLic - Comet License Retrieval / Installation Utility

SecLic is a utility which allows the retrieval and/or installation of the latest license certificate for your Comet Security Server. The license will be retrieved directly from a Signature Systems server and will be the most recent one issued for your security token. SecLic may be run either directly as a user utility or incorporated into your own application and ENTERed to run silently. Just be sure to have a WinSock gateway configured (a type 3 gateway).

To run it directly simply run SecLic from READY:

[[image:SecLic.jpg]]

To run it silently from your own app, you pass your choice of options via # buffer this way:

print (#) "OPT 1"

enter "SecLic" dir="REL"

input (#) Result$

There are 3 options:

* 1 - retrieve the latest certificate from the server and put it in the CometServices folder
* 2 - activate whatever certificate is in the CometServices folder
* 3 - retrieve and then activate
* 4 - retrieve expiration dates and license counts for currently installed certificate

The message you pass via the # buffer is case insensitive and any number of blanks are allowed between "opt" and the number. If the first 3 bytes of the buffer are anything other than ucase("opt") the dialog will display instead of running silently.

The result string will indicate the success or failure of the operation(s). It will begin with either "+OK" or "-ERR" and be followed by a descriptive message.

This utility is available on both Comet16 and Comet32 and for both USB and parallel plugs.

SecLic was added to the REL release in version 10.02 and requires Comet version .413 or higher and Comet Security Server version 10.0 or higher.

----

=== Notes for Option 4 ===

When run directly, the seclic program will have a button on the top of the screen titled "Check currently installed certificate" which, when pressed, will pop up a message box with license counts and expiration dates for your currently installed certificate.

[[image:SecLic-new.png]]

When ENTERed, specifying "OPT 4" will return the data in the following format:

<nowiki>
Position Length Description
===========================================================
1 8 Certificate Expiration Date
9 8 XAP Expiration Date (if applicable)
17 5 Number of Full Comet licenses
22 5 Number of Comet Anywhere licenses
27 5 Number of XAP licenses
</nowiki>

If an error occurs, the return string will have the following format: "-ERR -- error message"

File:Seclic-new.png

2023-07-01T00:29:31Z

Justin: new version of seclic

new version of seclic