URL directive

In the syntax presentations below:

• Square bracket characters [ and ] define optional parts of the directive. Do not type the brackets.
• Curly brace characters { and } mark the start and end of the directive.
• Replace any text in italics with your choice of value of that type.

{URL [action-specification] [options separated by spaces]}

Use quote marks as shown in the examples below.

The action-specification is either pyStream=myStream or pyActivity=myActivityClass.myActivityName.

When using the URL directive in a FORM tag, you can enter the action specification in either the form tag, the button tag, or the anchor tag. If you have more than one action specification, enter it in the button tag or the anchor tag, rather than in the form tag.

{URL [options separated by spaces]

Enter the action-specification in the anchor or submit button.

<A HREF="{URL pyStream=myStream PRIMARY}">
<B>MyAnchorText</B></A>

Options

This table lists each option and its corresponding property. Each option is explained in detail below.

Include the PRIMARY keyword unless the HTML rule is in the ultimate base class @baseclass (an unusual situation).

Enter	Or abbreviate as	To add this parameter
TRANSID	T	pzTransactionId
FRAME	F	pzFromFrame
PRIMARY	P	pzPrimaryPageName
LONG	L	Add all three properties

State synchronization (TRANSID option)

Used with a form and a SUBMIT button, the TRANSID option of the URL directive can be useful to maintain synchronization between the servers state and the user's browser state. Ideally, such synchronization works even when a user clicks the Back icon in the browser window.

The TRANSID keyword causes the pzTransactionID parameter value to be included in the URL.

When the browser state changes as the result of a user submitting an HTML stream, the pzTransactionID parameter stores the server state as it corresponds to the current browser stream, tracking where the user has been, and where the user is. In some situations, it is important that the browser state and the server state correspond accurately.

In situations where the server state data is not relevant, you can omit the TRANSID keyword.

Use this syntax to specify the TRANSID option:

<FORM = action = "{URL "" TRANSID PRIMARY}">my form HTML
<INPUT TYPE=Submit Name="pyStream=myStream">

The TRANSID keyword implies the FRAME keyword.

Target frame (FRAME Keyword)

Add the FRAME keyword to include the pzFromFrame property in the URL. Use this option if the target frame for the anchor is not the STANDARD frame, but is the current default frame. (The second parameter of the Show-HTML method determines the target frame for the HTML.)

<A HREF="{URL "pyStream=myStream" FRAME}">
<B>MyAnchorText</B></A>

The pzFromFrame property provides the default value for the pyTargetFrame parameter, the target frame used by the stream. If omitted, the system uses the STANDARD frame,

To add an explicit target frame, see below.

Called activity's primary page (PRIMARY keyword)

Add the PRIMARY keyword to the URL directive to instruct the system to include the value of the pzPrimaryPageName property in the URL when the user clicks an anchor or submit button.

Use this option to tell the system to use the default primary page as the primary page when a user clicks the anchor. If the activity the anchor calls expects a primary page, use the PRIMARY keyword or enter an explicit primary page using the pyPrimaryPageName property.

For example, an anchor that calls an activity to delete a page must indicate what page to delete. By contrast, an anchor that calls an activity that sets up its own primary page does not require the information.

Specify all options

To specify all three options, use the LONG keyword:

<A HREF="{URL "pyStream=myStream" LONG}">
<B>MyAnchorText</B></A>

You can append property-value pairs by property name to an anchor. To add property-value pairs, use an ampersand (&) character and enter the property value pair.

For example, you can cause an anchor to explicitly assign a primary page, using the pyPrimaryPageName parameter.

<a HREF="{URL pyActivity=myActivityClass.myActivity&pyPrimaryPageName=myPage}">
<b>MyAnchorText</b></a>

The clipboard page identified for pyPrimaryPageName must be a top-level page.

For another example, you can add an explicit target frame using the pyTargetFrame parameter.

<A HREF="{URL pyStream=myStream&pyTargetFrame=myLeftFrame}">
<B>MyAnchorText</B></A>

To use the URL directive with a Submit button, type the URL directive in the ACTION attribute of the Form tag like this:

<FORM action="{URL "" PRIMARY TRANSID FRAME}">

Reference the pyActivity or pyStream in the submit button.

<INPUT TYPE="Submit" NAME="pyActivity=Add">

When a user clicks the  Submit   button, the URL in the FORM tag is used.

Only activities that have the May Start? box on the Security tab may be started with the URL tag.

Suppressing options

Options for the URL directive promote transaction integrity between the client browser session and the requestor state on the PRPC server.

In most HTML forms, values for all of the options of the URL directive (TRANSID, FRAME, PRIMARY) are usually provided by hidden input fields such as:

<INPUT TYPE="HIDDEN" >

which the system adds immediately following a FORM tag.

The system does not add these inputs if the FORM tag specifies either:

• An ACTION attribute with a value not specified by a URL directive, or
• A METHOD attribute with a value other than POST.

Starting a new Thread

Execution of the URL directive can start execution of a new Thread for the current requestor. (A Thread is a context of clipboard user pages; it is not related to the UNIX thread.) Using the Property-Set method or a Java directive, set the name of a new Thread as the value of the pxThread.pyThreadUse property before the URL directive executes. The default Thread is named STANDARD; you can use any other alphabetic text can be used for the new thread name.