The PSOS script step

Today let's have a look at the PSOS (Perform Script on Server) script step introduced yesterday and the options it provides.

Specify script

The script that PSOS will run on the server can be specified in the same way as the standard Perform Script script step:

• From list – select a script from a list of available scripts
• By name – specify the script name with a calculation

In both cases, the script can either be from the same file or from another file set up as a FileMaker Data Source.

When specifying a script by name with a calculation, the script name is not case sensitive if the script is from the same file. However, for scripts from a different file, both the data source and the script name are case sensitive. The calculation must evaluate to:

‹ data source name › :: ‹ script name ›

Parameter

In the same way as the standard Perform Script script step, PSOS can send a parameter for the specified script with the request.

When using PSOS this parameter will usually include context for running the script. As mentioned yesterday, the script will run in an independent session on FileMaker Server. The server session does not inherit the caller’s context. This means that no assumptions can be made about the current layout, found set, current record, or any other context in the database.

When the server session is started up, it will run any script defined to trigger OnFirstWindowOpen. This may establish the same default context that a user sees when they open the database. For a PSOS script you will then want to use the script parameter data to establish the correct context for running the script. We will look more at this when we go through some examples.

Going back to our Peter Soss analogy yesterday, you will need to give Peter instructions on where to find the original document you want photocopied. This is the equivalent of the script parameter. We are assuming that Peter knows how to use the photocopier and where it is, so we don't need to send any context for that.

Wait for completion

The Wait for Completion option is a simple toggle that can be either On or Off.

When it is Off, the script that ran the PSOS script step simply continues on immediately with the next script step.

When it is On, this pauses the script running on the client until the script called by PSOS is completed on the host. The client may display a busy cursor or appear to wait. If you want to receive a script result or are depending on the outcome of the PSOS script to continue, then you must wait until the host has completed the script.

Using the Peter Soss analogy, you may want to have a copy of your document before you can continue your work. For example, you may be intending to mark up the copy of the contract you have asked Peter to make for you. For whatever reason, you decide to wait for Peter to come back with the copy instead of doing any other work.

This is the same as having Wait for Completion on. If something goes wrong, such as the photocopier breaking down, then Peter might return with an explanation as to why he has not done the job for you. This is the equivalent of a script result.

Alternatively you may decide to continue your work by marking up the copy of the contract you have in front of you. Peter can return at any time with another copy of the contract that you have requested. You aren’t waiting for him and Peter still gets on with the job. But he may never return with the copy and you would not know why.

Tomorrow we will look at why you might choose to use PSOS instead of running the script on the client.