TVStudy web servlet interface
-----------------------------

February 28, 2018
TVStudy version 2.2.5


Servlet requests are of the form:

http://server/tvstudy/api?op=operation...

where server is the Tomcat server hostname or IP address, and operation is one of the supported operations discussed in sections below.  All servlet requests must include at least the op parameter.


A number of parameters are common to several operations, those are:

user_record_id
Numerical integer ID for the user record table.  These IDs are abritrary and unique to a particular TVStudy database installation.  However the keys remain valid indefinitely for that installation; user records cannot be deleted.

ext_db_key
Key identifying the station data used for a record search.  For imported station data sets the key is arbitrary and unique to the database installation.  Imported data set keys may become invalid at any time due to user action from a desktop application using the same server.  Other special-purpose keys remain constant regardless of the installation or user action, those are:
  10005   LMS live server (if available)
  10102   Most recent LMS import
  10103   Most recent CDBS import

ext_record_id
Record ID in station data, either a CDBS application ID or an LMS filing version ID depending on the type of station data.

file_number
Record file number.  A file number prefix is optional, if present it is included in the match otherwise the match is just based on the ARN.  When a prefix does appear, a '-' separating the prefix from the ARN is optional.  Note ARNs defined in LMS must include the leading zeros, e.g. 10896 will not match anything, but 0000010896 will match the record with file number BLANK0000010896.


Interference-check study operations
-----------------------------------


ixcheck

Returns a page providing a form to enter search parameters to find a record to study, along with buttons to request pages to create a new record.  No other parameters.  After a search is performed and a record selected, or a new record is created, this will eventually send an ixchecksetup request.


ixchecksetup

Returns a page summarizing the parameters of the selected record, and providing a form to enter study settings and parameters.  Submitting the form will send an ixcheckrun request.  This must include one of the following parameters to specifically identify the study record, as discussed above:

user_record_id
ext_record_id
file_number

Only one of these should be present, if more than one appears the priority is user_record_id, ext_record_id, then file_number.

This request may also include the optional parameter:

ext_db_key
See above for discussion.  By default the search will use an imported data set with the name "Interference Check" if that exists, else the LMS live server if available, else it will use the most-recent TV imported data set.


ixcheckrun

Runs an interference-check study.  This may also immediately re-direct to cached output from a past identical run, if available, or it may return a page listing all available cached output from past runs for the identical study.  If a new run is started this re-directs to an index page, while the study is running that is a temporary page that will reload every few seconds until the study is complete.  This request must include one of the following parameters as discussed above:

user_record_id
ext_record_id
file_number

This request may also include the following optional parameters:

rerun
True/false flag.  If true a new run of the study will be started immediately even if cached results for a past run of the identical study already exist.  If false past run results will be shown if those exist otherwise a new run is started.  The default is false.

showpast
True/false flag.  Ignored if rerun is set.  Otherwise if true and cached results exist for one or more past runs of the identical study, the request will return an index page listing all available past run results plus a link for an immediate re-run of the study.  If false and cached results exist the request will redirect immediately to the most recent past run.  The default is false.

ext_db_key
Station data used for the study record search, as above.

study_ext_db_key
Station data used for the study build, this is the source for all other protected and undesired station records included in the study scenarios.  By default the build will use the same station data as the study record search.

replication_channel
If this value is present and valid, the study record will be replicated to the specified channel before building the study.  If the study record is a digital service, the replication channel is ignored if it is the same as the current channel.  Replicating an analog record converts it to an equivalent digital service, so an analog record can be replicated on the same channel.

template_key
Key identifying the template used to create the study.  Similar to station data keys, template keys are arbitrary and unique to a particular database installation, and may become invalid due to user action.  However key 1 will always represent the built-in default template.  By default the run will use a template with the name "Interference Check", however the template must also be locked but not study-locked, if the named template is not found or is not properly locked the run will use the built-in default template.

output_config
A code string that configures output files generated by the study run.  This is used to transfer settings from the ixchecksetup form, other requests should omit this so an appropriate default is used.

map_output_config
A code string for mapping-related output files and options.  As above.

cell_size
Study grid cell size in kilometers, legal range 0.1 to 10.  The default value is set in the application configuration file.

profile_pt_inc
Resolution for terrain profiles used for propagation models, spacing between points in kilometers.  Legal range is 0.02 to 1.  The default is set in the application configuration file.

profile_ppk
Alternative means of setting profile resolution, value in points/kilometer (inverse of the previous argument value).  If both arguments are present, profile_pt_inc takes precedence.

include_userids
A list of user record IDs separated by any whitespace.  The user records are included in the study build as if they are part of the study build station data.

include_foreign
True/false flag.  If true foreign records are included in the study build, else only U.S. records are included.  However note that the study record may be from any country regardless of this flag, and if the study record is foreign, other records for the same facility as the study record may still appear in the study even if this flag is false.  The default is set by preference (see Preferences section).

exclude_arns
A list of ARN strings separated by any whitespace.  Note these are not full file numbers, file prefixes must not be included.  Matching records will be excluded from the study build.

ignore_apps
True/false flag.  If true, records with APP status are excluded from the study build.  The default is false.

ignore_pending
True/false flag.  If true, pending license application records are excluded from the study build.  The default is false.

ignore_post_trans
True/false flag.  If true, post-transition records are excluded.  Post-transition records are all baseline records, and all non-license records filed after the baseline effective date for stations changing channel in the transition.  The default is false.

ignore_new_lptv
True/false flag.  If true, records for new LPTV stations are excluded (new means never licensed).  The default is set by preference (see Preferences section).

protect_non_bl
True/false flag.  This applies to records not on the same channel as the station's baseline facility, or for a station that does not have a baseline facility.  If this flag is false, such "non-baseline" records are ignored during the study.  If this is true, non-baseline records are included as protected records, and as undesireds when the protected being studied is a non-baseline record.  The default is false.

lptv_protect_bl
True/false flag.  If false, baseline records are not included as protected records when the study record is LPTV.  If true, baseline records are included.  The default is false.  This is ignored if the study record is not LPTV.

class_a_protect_lptv
True/false flag.  If true, LPTVs are included as protected records when the study record is a Class A.  If false, LPTVs are ignored.  If the study record sequence date is before the end of the post-auction filing window (as defined in the application configuration file), the default is false, but it may be set true.  If the study record date is after the window-end date, LPTVs must be protected by Class A; in that case this parameter is ignored, the associated flag is forced true and cannot be false.  This is ignored if the study record is not Class A.

cp_excludes_baseline
True/false flag.  If true, the presences of a CP record or a license record will exclude the station's baseline record (matched by facility ID) from the study.  Normally only a license record excludes the baseline.  The default is set by preference (see Preferences section).

filing_cutoff
Date.  If set, records with a sequence date after this date may be ignored.  When the study record is LPTV only other LPTV records after the cutoff are ignored.  When the study record is full-service or Class A, all records after the cutoff are ignored.


ixcheckcache

This operation with no parameters will return a page with status information about the cached output from interference-check study runs.  That page has buttons to trigger cache maintenance operations, including deleting cached output older than a specified number of days, and running a clean-up operation to remove cache rot.

Optional parameters:

cache_action
To trigger maintenance operations directly, include this parameter set to either the value "delete" or "cleanup".

delete_days
If cache_action is "delete" this parameter may be included, output older than this many days will be deleted.  The default is 60.  This may be 0 to delete the entire cache.


Examples:


Start an interactive interference-check study:

http://[server]/tvstudy/api?op=ixcheck


Run or retrieve a study with default settings for file number BLANK0000010896:

http://[server]/tvstudy/api?op=ixcheckrun&file_number=BLANK0000010896


Run or retrieve a study with default settings for CDBS application ID 1536931:

http://[server]/tvstudy/api?op=ixcheckrun&ext_record_id=1536931


Run or retrieve a study using 1-kilometer cells and 0.1-kilometer profile resolution for LMS record ID 175d20fd131e430baba9cf6212b6c0ea:

http://[server]/tvstudy/api?op=ixcheckrun&ext_record_id=175d20fd131e430baba9cf6212b6c0ea&cell_size=1&profile_pt_inc=0.1


Run the cache delete operation for files older than 30 days:

http://[server]/tvstudy/api?op=ixcheckcache&cache_action=delete&delete_days=30



Record lookup and search operations
-----------------------------------


search

Returns a page providing a form to select an available station data set and enter parameters to find a record in that data, or in the user record table.  No other parameters.  Submitting the form sends a searchrun request.


searchrun

Perform a search or record lookup.  Various parameters are included to identify a record or provide search criteria, as discussed below.  If the lookup or search returns a single record, this operation will chain directly to a searchshow request to display the record.  Otherwise it will return a page showing up to the first 50 matching records from the search allowing one to be chosen, then proceeding to a searchshow request when the selection is submitted.

user_record_id
As discussed above.  If this is present, it identifies a specific record and all other parameters are ignored.

ext_db_key
As discussed above.  If user_record_id is not present, this parameter must be present to identify the station data to be searched using other parameters; there is no default.

ext_record_id
file_number
As discussed above.  If either of these are present they are assumed to identify a single specific record in the station data so all other search parameters are ignored.  Only one of these should be present, if both appear ext_record_id has priority.

facility_id
Facility ID number.  This and later parameters are search criteria, used if neither ext_record_id nor file_number is present.  At least one of these criteria must be present.  If multiple search parameters are included, each narrows the search (criteria are combined with AND).

service
Record service, a two-letter code similar to the CDBS service codes, legal values are DT, DD, DC, LD, TV, CA, TX, DX, and TS.  Note these are not actually CDBS codes, they are TVStudy's internal service enumeration and all records in any data set will match one of these service types.  For example when searching an LMS data set, the LD service code will match all of the equivalent LMS services including LPD, LPT, and DRT; searching CDBS with code DT will match CDBS services DT and DS.

call_sign
Station call sign search, this is a head-anchored, case-insensitive substring match.  Wildcards are not supported.  Also the match is insensitive to the presence of D characters appearing in the station data, e.g. WXYZ will also match DWXYZ.

channel
Station channel number.

status
Record status code, legal values are APP, CP, LIC, STA, and EXP.

city
City of license search, unanchored case-insensitive substring match, * may be used as a wildcard to match any substring.

state
State code, case-insensitive exact match.

include_pending
True/false, true to include records with pending status in the search results.

include_archived
True/false, true to include archived (CDBS) or inactive (LMS) records in the search results.


searchshow

This operation displays data from a record selected by previous search operations.  The request must include either a valid user_record_id parameter, or valid ext_db_key and either ext_record_id or file_number parameters.  See description of those parameters above.



User record creation operations
-------------------------------


record

Returns a page providing a form to enter values for a new user record.  No other parameters are needed.  When the form is submitted, a recordsave request is sent.


recordsave

Save a new user record using parameters in the request.  Many parameters are required, others may have defaults, see individual discussions below.  Note this request currently can only save records with no directional antenna patterns, and it cannot save DTS records.

facility_id
Facility ID value.  This may be the ID for an existing station or an arbitrary value, but it must be included and the value must be >0.  All records in a given study with the same facility ID are considered mutually-exclusive and study logic will behave accordingly, in general all records in a given study scenario should have unique facility IDs.

service
Two-letter service code.  This parameter is required, and must be one of the legal values are DT, DD, DC, LD, TV, CA, TX, DX, or TS.

call_sign
Call sign, this is required, however the value is arbitrary.

channel
Channel number, this is required and must be a legal TV channel number 2-51.

status
This parameter is optional, a record may have no assigned status.  If provided the value is arbitrary.  However it is usually desireable to use one of the known values APP, CP, LIC, STA, or EXP.  Records with other/no status values may be treated as lower-priority by some study logic.

city
City name, required but arbitrary.

state
State code, required but arbitrary.

country
Country code, required and must be one of the legal values US, CA, or MX.

zone
Zone code, this is optional, but if provided it must be one of the legal values 1, 2, or 3.  The default is other/unknown.  As of this writing the study code only has variations in behavior for zone 1, so currently zones 2, 3, and other/unknown are equivalent and all mean "not zone 1".

frequency_offset
Frequency offset code, this is optional, but if provided it must be one of the legal values +, -, or Z.  The default is no offset.

emission_mask
Emission mask code.  This is required if the service code is DC or LD, in which case it must be one of the legal values S, T, or F for simple, stringent, or full-service.  For other service codes this parameter is ignored and need not be present.

latitude_direction
latitude_degrees
latitude_minutes
latitude_seconds
longitude_direction
longitude_degrees
longitude_minutes
longitude_seconds
Coordinate parameters are all required, they must all be present and valid.  Latitude direction is N or S, longitude is W or E.  Degrees and minutes are integers, seconds may be fractional.  All must be in legal range.

height_amsl
Antenna AMSL height in meters, this is required.  Legal range is -1000 to 10000.  The special value -999 will request that the AMSL height be determined when the record is used in a study.  In that case, if an HAAT value is provided (see below) the AMSL height will be derived from the HAAT using average terrain from the selected terrain database.  If the HAAT value is also -999, the AMSL height is set to the ground elevation from the terrain database plus the study parameter value for minimum transmitter AGL height.

haat
Antenna HAAT (height above average terrain), this is required.  Legal range is -1000 to 10000.  As with the AMSL height this may be the special value -999 to have the HAAT computed using the selected terrain database when the record is used in a study.

peak_erp
Peak ERP in kilowatts, this is required.  Legal range is 0.00001 to 5000.

comment
Arbitrary comment text attached to the record.  Optional, default is blank.



Preferences operations
----------------------


prefs

View and set preferences for the servlet installation.  Preferences are stored in a local properties file and so are independent of the database being used.  With no parameters, this will return a page displaying the current preference settings and allowing those to be changed.  If parameters listed below are included in the request, the preferences are set to those values first.

include_foreign
True/false flag, sets the default for this parameter in ixchecksetup and ixcheckrun operations.

ignore_new_lptv
True/false flag, sets the default for this parameter in ixchecksetup and ixcheckrun operations.

cp_excludes_baseline
True/false flag, sets the default for this parameter in ixchecksetup and ixcheckrun operations.
