Robo-FTP User's Guide > Robo-FTP Framework > Advanced

The Robo-FTP Enterprise Framework allows you to construct your own custom steps. By creating a .ini file and matching .s script file and placing these in your "%roboftpinstalldir\FrameWork\Modules" directory, the step will instantly become available to the job designer.

Consider the following custom step, httpget, whose purpose is to retrieve a resource available over HTTP using a URL with an optional "query" part.

The first function in your custom step should be named after the filename, minus the ".s" part. Therefore, in this case we will call the function "httpget". This is the entry point of the step and generally is used to select between the "verification phase", where certain parameters are verified for correctness at the start of the job run, or else the "execution phase". The function will branch off to the function "httpget_verify" if the verification phase is active. If this function does not return $ERROR_SUCCESS, the "httpget" function will call the internally defined "complete_step_final" framework function with %lasterror set to the actual error returned from the verification function. The framework will detect the error and terminate the job before even the first step has been run. The syntax for this function is as follows:

complete_step_final source_directory target_directory %step_name config_index %lasterror

The "source_directory" is where files from the previous step (if any) reside. The "target_directory" is where the files at the end of the current step should reside. Generally these will be %instsalldir\ProgramData\FrameWork\data\%jobgroup\%jobname\%jobrun\%step_name_prev\files and %instsalldir\ProgramData\FrameWork\data\%jobgroup\%jobname\%jobrun\%step_name\files. Finally, the %lasterror is the error that will be reported to the framework.

Let's discuss the execution phase. Generally the actual execution of a step will take place in a function named after the step plus "_step". For example, our "httpget_step" here. When calling this step we include all arguments mentioned in the .ini file so that they are accessible to it for processing. Generally, inside the actual function these arguments will be prefixed with a few characters to prevent them from being overwritten elsewhere in the framework. e.g. site -> hgs_site. In our case, this function downloads files directly to the target_directory (or rather, hgs_target_directory), and finally reports any errors in the preceding RCVFILE using the internal framework function "complete_step".

This functions similarly to the complete_step_final but reports instead on the status of individual operations, generally file operations:

complete_step hgs_query %downloadsize %datetime %lastpath %lasterror

Finally, we return to the main httpget function where we call

complete_step_final source_directory target_directory %step_name config_index %lasterror

again, just like with the verify phase.

Putting everything together, the full custom step is:

BEGINFUNCTIONS

FUNCTION httpget

IFSTRCMP master_phase "verify" GOTO verify

httpget_step target_directory site path query target

complete_step_final source_directory target_directory %step_name config_index %lasterror

RETURN %lasterror

:verify

httpget_verify site

complete_step_final source_directory target_directory %step_name config_index %lasterror

RETURN %lasterror

ENDFUNCTION

FUNCTION httpget_verify hv_site

FTPLOGOFF

FTPLOGON hv_site

IFERROR RETURN

FTPLOGOFF

RETURN $ERROR_SUCCESS

ENDFUNCTION

FUNCTION httpget_step hgs_target_directory hgs_site he_path hgs_query hgs_target

FTPLOGOFF

FTPLOGON hgs_site /allowerrors

IFERROR RETURN

FTPCD hgs_path

IFERROR RETURN

CD hgs_target_directory

IFERROR RETURN

RCVFILE he_target /from=hgs_query

complete_step hgs_query %downloadsize %datetime %lastpath %lasterror

RETURN %lasterror

ENDFUNCTION

ENDFUNCTIONS

Creating Custom Steps

Creating Custom Steps